> ## Documentation Index
> Fetch the complete documentation index at: https://orchata.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Reference

> Complete reference for all Orchata CLI commands

## orchata init

Configure the CLI to connect to the Orchata cloud API. Run this once after installing.

```bash theme={null}
orchata init
```

You can also pass values directly:

```bash theme={null}
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.

```bash theme={null}
orchata login
```

Provide an API key non-interactively:

```bash theme={null}
orchata login --api-key oai_...
```

Use a named profile:

```bash theme={null}
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 |

***

## orchata configure

Update saved settings like profile, API base, and app base.

```bash theme={null}
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

```bash theme={null}
orchata spaces list
```

Filter by metadata:

```bash theme={null}
orchata spaces list --metadata '{"team":"engineering"}'
```

| Option              | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--metadata <json>` | Filter by metadata key-value pairs (JSON string) |

### Create a space

```bash theme={null}
orchata spaces create --name "Docs" --description "Product docs" --icon book
```

With metadata:

```bash theme={null}
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

```bash theme={null}
orchata spaces get space_123
```

### Update a space

```bash theme={null}
orchata spaces update space_123 --name "Updated"
```

Update metadata:

```bash theme={null}
orchata spaces update space_123 --metadata '{"team":"product","priority":"high"}'
```

### Delete a space

```bash theme={null}
orchata spaces delete space_123
```

<Note>
  Deleting a space archives it (soft delete). The space and its documents remain accessible but hidden.
</Note>

***

## orchata documents

Manage documents within a space.

### List documents

```bash theme={null}
orchata documents list --space space_123
```

Filter by metadata:

```bash theme={null}
orchata documents list --space space_123 --metadata '{"category":"docs"}'
```

### Upload a document

Upload a file:

```bash theme={null}
orchata documents upload ./file.md --space space_123
```

Upload inline content:

```bash theme={null}
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

```bash theme={null}
orchata documents get document_123 --space space_123
```

### Get document content

Retrieve the processed text content:

```bash theme={null}
orchata documents content document_123 --space space_123
```

### Append to a document

```bash theme={null}
orchata documents append document_123 --space space_123 --content "- New item"
```

### Batch upload

Upload all files in a directory:

```bash theme={null}
orchata documents batch ./docs/ --space space_123
```

***

## orchata query

Query one or more spaces using semantic search.

### Basic query

```bash theme={null}
orchata query "authentication flow" --space space_123
```

### Smart query

Discover relevant spaces automatically:

```bash theme={null}
orchata query smart "what is orchata"
```

### Options

```bash theme={null}
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)    |