orchata init
Configure the CLI to connect to the Orchata cloud API. Run this once after installing.
You can also pass values directly:
orchata init --api-base https://api.orchata.ai --app-base https://app.orchata.ai
| Option | Description |
|---|
--api-base <url> | API base URL |
--app-base <url> | App base URL |
orchata login
Authenticate with your API key. Opens the signup page in your browser if you don’t have an account yet.
Provide an API key non-interactively:
orchata login --api-key oai_...
orchata login --profile production
| Option | Description |
|---|
--api-key <key> | Provide API key non-interactively |
--profile <name> | Use a named profile |
--host <url> | Override API base URL |
--no-open | Don’t open the signup page in browser |
Update saved settings like profile, API base, and app base.
orchata configure --api-base https://api.orchata.ai
orchata configure --profile staging --set-default
| Option | Description |
|---|
--profile <name> | Select a profile to modify |
--api-base <url> | Set the API base URL |
--app-base <url> | Set the app base URL |
--api-key <key> | Set the API key |
--set-default | Make this profile the default |
orchata spaces
Manage knowledge base spaces.
List spaces
Filter by metadata:
orchata spaces list --metadata '{"team":"engineering"}'
| Option | Description |
|---|
--metadata <json> | Filter by metadata key-value pairs (JSON string) |
Create a space
orchata spaces create --name "Docs" --description "Product docs" --icon book
orchata spaces create --name "Docs" --description "Product docs" --icon book --metadata '{"team":"engineering","project":"api-v2"}'
| Option | Description |
|---|
--name <name> | Space name (required) |
--description <text> | Space description |
--icon <icon> | Space icon (folder, book, file-text, database, etc.) |
--metadata <json> | Custom metadata as a JSON string |
Get a space
orchata spaces get space_123
Update a space
orchata spaces update space_123 --name "Updated"
orchata spaces update space_123 --metadata '{"team":"product","priority":"high"}'
Delete a space
orchata spaces delete space_123
Deleting a space archives it (soft delete). The space and its documents remain accessible but hidden.
orchata documents
Manage documents within a space.
List documents
orchata documents list --space space_123
orchata documents list --space space_123 --metadata '{"category":"docs"}'
Upload a document
Upload a file:
orchata documents upload ./file.md --space space_123
orchata documents upload --space space_123 --content "# Title\n\nContent here..."
| Option | Description |
|---|
--space <id> | Target space ID (required) |
--content <text> | Inline content to upload |
Get a document
orchata documents get document_123 --space space_123
Get document content
Retrieve the processed text content:
orchata documents content document_123 --space space_123
Append to a document
orchata documents append document_123 --space space_123 --content "- New item"
Batch upload
Upload all files in a directory:
orchata documents batch ./docs/ --space space_123
orchata query
Query one or more spaces using semantic search.
Basic query
orchata query "authentication flow" --space space_123
Smart query
Discover relevant spaces automatically:
orchata query smart "what is orchata"
Options
orchata query "onboarding" --space space_123 --top-k 5
| Option | Description |
|---|
--space <id> | Space ID to query (required for basic query) |
--top-k <n> | Maximum number of results (default: 10) |
--metadata <json> | Filter by document metadata (JSON string) |
