---
title: 'flexkit chat'
description: "Talk to the project's Chat Agent from the terminal, and list, read, stop or delete your chats."
---

# `flexkit chat`

Talks to the project's [Chat Agent](/docs/ai/agent-chat) from the terminal. The chats are the same ones you see in the Studio AI app: a chat started in the terminal can be continued in Studio, and the other way round.

With a prompt, the command sends it and streams the reply to stdout as plain text, so you can pipe or redirect it. The tools the agent calls are shown dimmed on stderr. The command exits when the turn ends. Without a prompt, in a terminal, it opens an interactive session.

## Synopsis

```bash
flexkit chat [prompt | -] [--chat <chatId>] [--model <modelId>] [--json] [options]
flexkit chat <subcommand> [arguments] [options]
```

## Requirements

- **A login session.** The chat acts as you: it uses your role and spaces, and your chats are private to you. Sign in with [`flexkit login`](/docs/cli/login). API tokens (`FLEXKIT_TOKEN` or `--token flk-…`) are refused with *This command acts as you, so it needs a login session*.
- **Any project role.** Owners, developers, editors, contributors and viewers can chat. What the agent may read or change follows your role.
- When you are an owner or developer and [`flexkit dev`](/docs/cli/dev) is running, the agent calls your local custom tools, as it does in Studio.

## Send a prompt

```bash
flexkit chat "<prompt>" [--chat <chatId>] [--model <modelId>] [--json]
flexkit chat - < prompt.txt
flexkit chat --message "<prompt>"
flexkit chat -- <prompt words…>
```

- The prompt can be quoted or written as plain words: `flexkit chat which products have no price` works.
- `-` reads the prompt from stdin.
- Without `--chat`, a new chat starts. When the reply ends, stderr shows the command to continue it.
- With `--chat <chatId>`, the message goes to that chat. If no turn is running, it starts the next turn. If the agent is still working, the message joins the running turn or runs right after it, as in Studio. If the agent is waiting for an answer to a question, your message is the answer.
- Press Ctrl+C while the agent is working to stop the turn (like the Stop button in Studio). Press it again to quit at once.

### Questions and approvals

The agent sometimes stops and waits for you. It may ask a multiple-choice question, or it may propose a change to your data that needs approval.

- **In a terminal**, the CLI asks you right there. For a question you pick options or type your own answer. For a change you can approve it, reject it with an optional reason, show the operations, or leave it pending. After you answer, the reply keeps streaming.
- **Without a terminal** (scripts, CI, pipes) or with `--json`, the command stops, prints the question or the proposed change on stderr with the command to continue, and exits with code `3`. Answer a question with `flexkit chat --chat <chatId> "<answer>"`. Review a change with [`flexkit approvals`](/docs/cli/approvals) or in Studio.

### Examples

```bash
# Ask a question and stream the answer
flexkit chat "Which five products sold best last week?"

# Continue the same chat
flexkit chat --chat 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13 "Now only the ones in stock"

# Send a brief from a file and save the reply
cat brief.md | flexkit chat - > reply.md

# A prompt that starts with a subcommand name
flexkit chat -- ls the products without a price

# Use a specific model for this turn
flexkit chat --model anthropic/claude-sonnet-5:high "Summarize yesterday's orders"
```

## Interactive session

```bash
flexkit chat [--chat <chatId>]
```

Run `flexkit chat` with no prompt in a terminal to chat back and forth. Each line you type is sent, and the reply streams below it.

- `/new` starts a new chat with the next message.
- `/exit` or `/quit` (or Ctrl+C at the prompt) leaves.
- Ctrl+C while a reply streams stops that turn and returns to the prompt.

With `--chat`, the session continues an existing chat.

### Examples

```bash
# Start an interactive session
flexkit chat

# Continue a chat interactively
flexkit chat --chat 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13
```

## `chat ls`

Lists your chats in the project, most recent first. With `--search`, it searches what was said in your chats, by keyword and by meaning, and shows the best match per chat (up to 30).

```bash
flexkit chat ls [--search <query>] [--limit <n>] [--offset <n>] [--json]
```

### Examples

```bash
# List your recent chats
flexkit chat ls

# Find the chat where you discussed refunds
flexkit chat ls --search "refund policy"

# Print the ids and titles of your last 100 chats
flexkit chat ls --limit 100 --json | jq -r '.[] | "\(.id) \(.title)"'
```

## `chat show`

Prints the transcript of a chat. It shows your messages, the agent's replies, the tools it called and the files it created. It also lists questions and changes that still wait on you, and the monitors that still watch for the chat. Interactive views the agent drew are replaced by a note; open the chat in Studio to see them.

```bash
flexkit chat show <chatId> [--all] [--json]
```

Without `--all`, the latest 50 messages are shown.

### Examples

```bash
# Read a chat
flexkit chat show 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13

# Print the whole history of a long chat
flexkit chat show 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13 --all

# Get the text of the last reply
flexkit chat show 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13 --json | jq -r '.messages[-1].textContent'
```

## `chat stop`

Stops the turn the agent is working on in a chat. What it wrote so far is kept. Questions and change proposals from that turn are cancelled. A message you sent while it worked runs as the next turn.

```bash
flexkit chat stop <chatId> [--json]
```

### Examples

```bash
# Stop a long-running turn
flexkit chat stop 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13
```

## `chat rename`

Renames a chat.

```bash
flexkit chat rename <chatId> <title> [--json]
```

### Examples

```bash
# Give a chat a clear title
flexkit chat rename 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13 "Q3 price update"
```

## `chat rm`

Deletes a chat and its messages. The CLI asks for confirmation first. Pass `--yes` to skip the prompt; without a terminal, `--yes` is required.

```bash
flexkit chat rm <chatId> [--yes] [--json]
```

### Examples

```bash
# Delete a chat (asks first)
flexkit chat rm 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13

# Delete a chat in a script
flexkit chat rm 3f6c1a52-8d4e-4b7a-9c1e-2a5b7d9e0f13 --yes
```

## Prompts and subcommand names

A first word is read as a subcommand only when the rest of the command fits that subcommand:

- `ls` (or `list`) with nothing after it
- `show`, `stop`, `rm` (or `remove`) followed by exactly one chat id
- `rename` followed by a chat id and a title

Anything else is a prompt, so `flexkit chat show me last week's orders` asks the agent. To send a prompt that would match a subcommand, put it after `--` or pass it with `--message`:

```bash
flexkit chat -- ls
flexkit chat --message "stop"
```

## Options

| Option | Description |
| --- | --- |
| `--chat`, `-c <chatId>` | Continue this chat instead of starting a new one. Also answers a question the chat waits on. |
| `--message`, `-m <text>` | The prompt, for text that starts with a subcommand name. Same as a prompt after `--`. |
| `--model <modelId>` | Model for this turn: `auto`, a model id such as `anthropic/claude-sonnet-5`, optionally with a reasoning effort (`anthropic/claude-sonnet-5:high`). Default: the chat's model, or `auto`. |
| `--json` | Prompt: print the raw stream as NDJSON on stdout (see below). Subcommands: print the API response as JSON. |
| `--search <query>` | `ls`: search your chat messages instead of listing chats. |
| `--limit <n>` | `ls`: number of chats to list. Default: 30. |
| `--offset <n>` | `ls`: number of chats to skip. Default: 0. |
| `--all` | `show`: print the whole history. Default: the latest 50 messages. |
| `--yes`, `-y` | `rm`: delete without asking. |
| `--project`, `-p <id>` | Project to use. Default: the [linked](/docs/cli/link) project. |

See also the [global options](/docs/cli/global-options).

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | The turn finished. |
| `1` | The turn failed, or the request was refused. |
| `3` | The turn waits on your answer or approval, and the CLI could not ask (no terminal, or `--json`). |
| `130` | You stopped the turn with Ctrl+C. |

## Scripting

`--json` turns the reply into machine-readable output. The first line describes the turn, and each following line is one chunk of the stream, in the same format Studio renders:

```json
{"type":"flexkit-turn","chatId":"3f6c1a52-…","workflowRunId":"wrun_…","userMessageId":"…","assistantMessageId":"…"}
{"type":"text-delta","id":"0","delta":"The best seller is"}
{"type":"tool-input-available","toolCallId":"…","toolName":"executeGraphqlQuery","input":{"query":"…"}}
{"type":"data-run-artifact","data":{"filename":"orders.csv","status":"done","url":"https://…"}}
{"type":"finish","messageMetadata":{"flexkitTerminal":true}}
```

```bash
# Keep only the reply text
flexkit chat --json "List products without a price" | jq -rj 'select(.type == "text-delta") | .delta'

# Collect the links of files the agent created
flexkit chat --json "Export this month's orders as CSV" \
  | jq -r 'select(.type == "data-run-artifact" and .data.status == "done") | .data.url'

# Reuse the chat id for a follow-up
CHAT=$(flexkit chat --json "Draft a price update for winter jackets" | head -1 | jq -r .chatId)
flexkit chat --chat "$CHAT" "Lower it to 10 percent"
```

Plain text mode is pipe-friendly too: the reply goes to stdout, while tool calls, notices and errors go to stderr.


---

[View full sitemap](/docs/sitemap.md)