# CLI

`boru/ai` includes CLI utilities built on `boru/cli2`.

For the fluent chat callback surface used by the chat command, see `chat.md`. For replay and persistence behavior behind resumed conversations, see `replay.md` and `persistence.md`.

Current commands include:

- `chat`
- `conversation:show`
- `persistence:prune`
- `tool-calls:list`

## Chat command

The `chat` command supports:

- provider overrides
- model overrides
- resuming by external conversation reference
- resuming by internal conversation id
- inline file attach syntax such as `@file /path/to/file.pdf`

### Example

```bash
php bin/ai chat --provider gemini --model gemini-2.5-pro --reference demo_chat
```

Inside the interactive session:

```text
> Summarize the attached document @file /tmp/demo.pdf
```

The chat command now uses the fluent stream delta helper internally for streamed terminal output.

If you are attaching files, also review `assets.md`.

## Conversation inspection

Use the conversation inspection command to view a stored conversation and its turns.

## Tool call inspection

Use the tool call inspection command to view persisted tool lifecycle rows when tool-call persistence is enabled.

## Persistence pruning

Use the persistence prune command to remove old DB-backed persistence rows on a schedule.

It defaults to a dry run. Pass `--execute` to actually delete rows.

Example dry run:

```bash
php bin/ai persistence:prune --before "30 days ago" --scope conversations
```

Example actual prune suitable for cron:

```bash
php bin/ai persistence:prune --before "90 days ago" --scope conversations --execute
```

Supported scopes:

- `conversations` deletes matching conversations plus dependent turns, tool calls, and conversation notes
- `turns` deletes matching turns plus dependent tool calls
- `tool_calls` deletes matching tool call rows only
- `all` applies all prune passes for the cutoff

## Design note

The CLI is both:

- a useful developer utility
- a practical end-to-end integration harness for the library

## See also

- `chat.md`
- `replay.md`
- `assets.md`
- `persistence.md`
