On this page

Use the command line

Install the CLI

Use Python 3.11 or newer. From the checkout root, run:

python -m pip install './sdk/python[cli]'
contextbase --version

For a published SDK release with the CLI, install python -m pip install 'contextbase-sdk[cli]'. See package metadata. --help and --version work offline.

Connect to a Space

Create a read key for the indexed Next Product Lab sample guide from Installation and quickstart. Follow Use ContextBase from an application to get the Space UUID. Set CONTEXTBASE_API_KEY through your secret manager, or pass --key-file with a file readable only by your account.

Replace SPACE_UUID with the Space UUID. The URL below is for a local installation.

contextbase --base-url http://localhost:13000 --space SPACE_UUID \
  search 'How early should I prepare draft release notes before the demo?'

The matching passage gives at least two working days before the demo. Use documents list to check whether the guide is indexed.

Save a profile

contextbase profile set local --url http://localhost:13000 --default-space SPACE_UUID
contextbase --profile local meta
contextbase --profile local spaces list

meta checks server compatibility without a key. profile list lists saved URLs and default Spaces. Profiles store no keys.

Put global options before the command, for example contextbase --profile local --key-file /secure/contextbase.key spaces list.

  • --profile overrides CONTEXTBASE_PROFILE. The default is default.

  • --base-url and --space override CONTEXTBASE_BASE_URL and CONTEXTBASE_SPACE. Environment values override profile values.

  • --key-file takes precedence over CONTEXTBASE_API_KEY.

  • CONTEXTBASE_CONFIG overrides the default path to profiles.json.

  • --timeout sets the SDK request timeout. The default is 60 seconds.

Upload, wait and ask a question

Give the key write access. Download the Next Product Lab sample guide or use your own document. The commands use the Space saved in the profile.

contextbase --profile local documents upload ./next-product-lab-demo-en.txt --wait
contextbase --profile local documents list

Pass a directory to upload multiple files. Use --recursive to include subdirectories and --include '*.txt' to match filenames. --wait waits for indexing for up to 300 seconds. Set --wait-timeout to change that limit.

If the server returned IDs and waiting failed, resume with those IDs. Check documents list before retrying an upload with an uncertain outcome. Ctrl+C ends the local wait. Server work can continue.

contextbase --profile local documents get DOCUMENT_UUID
contextbase --profile local documents wait DOCUMENT_UUID --wait-timeout 600

Generate or stream an answer

Connect a language model and enable generation in the Space. See Installation and quickstart.

contextbase --profile local query 'How early should I prepare draft release notes before the demo?'
contextbase --profile local --output ndjson query 'How early should I prepare draft release notes before the demo?' --stream

query returns an answer and its sources. For streaming, --deadline limits the entire request, including waiting for events. The default is 300 seconds. See Use ContextBase from an application for the response fields.

Configure and evaluate a pipeline

  • presets list lists pipeline presets. Apply the search pipeline with presets apply search --yes. Track the rebuild with presets status. Configure an agent graph separately as shown in Generate answers and inspect their sources.

  • With a dataset and an authorized key, submit a run with evaluations run DATASET_UUID. Pass its returned ID to evaluations get RUN_UUID. See Evaluate retrieval and answers.

Read results from scripts

contextbase schema > commands.json
contextbase --profile local --output json --non-interactive documents list

text is the default terminal format. JSON returns one object with schema_version, event and data. Failures add error. Progress and diagnostics go to stderr. Check the exit status and keep returned IDs for status requests.

Use --output ndjson with query --stream. Each line contains one stage, check, token, done or error event. Append data.delta for tokens and read the final answer and sources from data.answer in done. Require done and exit status zero.

On a failed batch, JSON and NDJSON keep accepted IDs in data.uploaded and classify paths as failed, unknown or unattempted. Track accepted IDs until indexing completes.

Call a specific API operation

Use contextbase api <resource> <operation> for calls beyond the workflow commands. The generated commands cover operations available to API keys, plus public server metadata and setup status.

contextbase api --help
contextbase api spaces get-space --help
contextbase --profile local --output json api spaces get-space --id "$SPACE_ID"
contextbase --profile local --output json api spaces list-spaces --page 2

Set SPACE_ID to your Space UUID. Generated commands take explicit API parameters such as --id or --space-id and return one page per call. Workflow list commands collect all pages.

Use --body or --body-file for JSON, --file for upload and --save-to for download. Deletion requires --yes. See REST API reference for permissions and the REST contract. See the SDK CLI guide for exit codes and completion.

ContextBase0.1.0

Search the documentation