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.
--profileoverridesCONTEXTBASE_PROFILE. The default isdefault.--base-urland--spaceoverrideCONTEXTBASE_BASE_URLandCONTEXTBASE_SPACE. Environment values override profile values.--key-filetakes precedence overCONTEXTBASE_API_KEY.CONTEXTBASE_CONFIGoverrides the default path toprofiles.json.--timeoutsets 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 listlists pipeline presets. Apply the search pipeline withpresets apply search --yes. Track the rebuild withpresets 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 toevaluations 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.