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

# Chat

> `gcai chat` commands.

## `gcai chat create`

Create chat completion

```bash theme={null}
gcai chat create <message> [--file-ids <value>…] [--playbook-ids <value>…] [--playbook-id <value>] [--skill-ids <value>…] [--chat-id <value>] [--project-id <value>] [--company-id <value>] [--async] [--timeout <seconds>]
```

| Flag                      | Type       | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--file-ids <value>…`     | `string[]` |          | Optional uploaded file IDs to attach as context for this completion. Upload files first via `POST /files`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--playbook-ids <value>…` | `string[]` |          | Optional playbook IDs to ground the completion in (up to 20). The model uses each playbook's checks and guidance to structure its review of the attached files. Discover playbooks via `GET /playbooks`. Org-scoped keys can use org-visible and official playbooks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `--playbook-id <value>`   | `string`   |          | Deprecated and no longer accepted. Use `playbook_ids` (an array) instead. Requests that include this field are rejected with a 400 so the playbook is never silently dropped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--skill-ids <value>…`    | `string[]` |          | Optional skill IDs to run on the first turn. Each skill's instructions are injected as context for this completion. Discover skills via `GET /skills`. Only valid when starting a new chat; omit them when continuing with `chat_id`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--chat-id <value>`       | `string`   |          | Optional chat ID to continue an existing conversation, from the `chat_id` of a prior completion. Omit to start a new chat. Conversation state is held server-side, so send only your new `message` (plus any new `file_ids`); do **not** re-send prior turns or previously returned documents/emails/diagrams. Only one turn may be in flight per chat at a time. See [Multi-turn Conversations](/api-reference/concepts/multi-turn).                                                                                                                                                                                                                                                                                                                                                                        |
| `--project-id <value>`    | `string`   |          | Optional project to file the chat into, so it is browsable under `GET /projects/{id}/chats`. Requires write access to the project. The chat becomes visible in the project once you materialize it. Discover projects via `GET /projects`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `--company-id <value>`    | `string`   |          | Optional company profile to ground the completion in, so the model has that company's context (industry, jurisdiction, regulations, risk posture). Discover company profiles via `GET /company-profiles`. The company is fixed for the life of a chat. On a new chat, supply this to target a specific company (the only way to ground against a particular one in a multi-company organization); when omitted, a company is auto-resolved: user-scoped keys use the caller's active (default) company, and org-scoped keys use the organization's sole company, or none when there are several. When continuing a chat with `chat_id`, omit this to reuse the chat's company. You may echo the same `company_id`, but a different one is rejected with `409` (start a new chat to use a different company). |
| `--async`                 | `boolean`  |          | Return the pending job immediately instead of waiting.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--timeout <seconds>`     | `number`   |          | Client-side wait bound before giving up (default 300).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

Wraps `POST /chat/completions` — see [Create chat completion](/api-reference/create-chat-completion) for full parameter semantics.

## `gcai chat materialize`

Materialize an API chat

```bash theme={null}
gcai chat materialize <id> [--project-id <value>]
```

| Flag                   | Type     | Required | Description                                                                                                                   |
| ---------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--project-id <value>` | `string` |          | File the chat into this project while materializing it. Requires write access to the project. Omit to leave the chat unfiled. |

Wraps `POST /chat/{id}/materialize` — see [Materialize an API chat](/api-reference/materialize-chat) for full parameter semantics.

## `gcai chat search`

Search chats

```bash theme={null}
gcai chat search <q> [--limit <number>]
```

| Flag               | Type     | Required | Description                              |
| ------------------ | -------- | -------- | ---------------------------------------- |
| `--limit <number>` | `number` |          | Max chats to return (default 20, max 50) |

Wraps `GET /chat/search` — see [Search chats](/api-reference/search-chats) for full parameter semantics.