<!-- SPDX-License-Identifier: Apache-2.0 -->

# CLI reference

`cireilclaw` starts the runtime host when invoked without a command.

Every command accepts `-r|--root <PATH>` to select the runtime root; the default is `~/.cireilclaw`.

## Commands

| Command   | Purpose                                             |
| --------- | --------------------------------------------------- |
| `run`     | Start the runtime host (default).                   |
| `logs`    | Display structured runtime logs.                    |
| `init`    | Create the runtime and scaffold agents.             |
| `dry-run` | Validate configuration without starting or writing. |
| `status`  | List configured agents.                             |
| `migrate` | Apply pending configuration migrations.             |
| `clear`   | Clear one or more persisted sessions.               |
| `repair`  | Repair Discord session media and history.           |
| `codex`   | Manage OpenAI Codex OAuth credentials.              |
| `update`  | Check, install, or roll back a published binary.    |
| `remote`  | Administer paired adapters and remote sessions.     |

Use `cireilclaw <command> --help` for command-specific arguments.

`run`, `dry-run`, and `status` display agent tables in ordinal slug order without a timestamp prefix. If no agents are found, they instead print a timestamped notice to stderr.

## run

Starts the runtime host and keeps it alive until shutdown.

| Option            | Description                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--once`          | Initialize and exit without waiting.                                                                                  |
| `--level <LEVEL>` | Terminal diagnostic verbosity: `trace`, `debug`, `info`, `warning`, `error`, `critical`, or `none` (default `debug`). |
| `-v`, `--verbose` | Alias for debug output.                                                                                               |

`run` prints timestamped startup and shutdown status messages. It exits early with `--once` or when no agents are configured.

## logs

Displays the most recently modified structured log file in the normal human-readable format.

| Option                 | Description                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| `-a`, `--agent <SLUG>` | Include only events whose structured `AgentSlug` property exactly matches the requested slug.  |
| `-s`, `--session <ID>` | Include only events whose structured `SessionId` property exactly matches the requested id.    |
| `-f`, `--follow`       | Start at the end of the active file and continue printing complete events as they are written. |

Following continues across daily and size-based log rotation. Agent-filtered output excludes events that do not carry an `AgentSlug` property. Session-filtered output excludes events that do not carry a `SessionId` property, and `--session` combines with `--agent` so both filters must match.

## init

Creates the runtime root and its `config/` and `agents/` directories.

| Option                | Description                                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent <NAME>`      | Scaffold an agent; the slug is derived from the name.                                                                                                                                 |
| `--force`             | Move an existing agent aside before scaffolding.                                                                                                                                      |
| `--api-base <URL>`    | Provider API base URL for the generated template; defaults to the selected provider's backend (`https://api.openai.com/v1`, or `https://chatgpt.com/backend-api` for `openai-codex`). |
| `--provider <KIND>`   | Provider kind: `openai`, `anthropic`, or `openai-codex` (default `openai`).                                                                                                           |
| `--model <NAME>`      | Default model for the generated template (default `replace-me`).                                                                                                                      |
| `--print-stub <NAME>` | Print a template to stdout instead of writing files; valid names are `core`, `soul`, `identity`, `person`, `long-term`, and `style-notes`.                                            |

## dry-run

Validates startup configuration without starting the host or writing runtime state.

It loads compiled plugins and validates each agent's providers, sandbox, enabled tool names, conditions, heartbeat, cron jobs and expression syntax, and optional Discord configuration. An enabled remote listener also validates its TLS identity. It prints the validated agent list without starting adapters, schedulers, or inference, and without creating session databases or migration state. It does not build an agent's system prompt or validate `core.md`, memory-block frontmatter, or skill contents; those are loaded when a turn builds its prompt. A successful check does not prove external connectivity or port availability.

## status

Lists agents discovered in the runtime data directory.

## migrate

Applies pending configuration migrations without starting the runtime host.

| Option          | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------- |
| `--dry-run`     | List pending migrations without applying them.                                        |
| `--mode <MODE>` | Select `run-all`, `step-through`, or `cancel`; aliases are `all`, `step`, and `none`. |

Migrations also run automatically at runtime startup.

Without `--mode`, an interactive terminal prompts for a mode; noninteractive invocation runs all pending migrations. `step-through` asks for confirmation before each migration.

## clear

Clears one or more persisted sessions without starting the runtime host.

| Option           | Description                                             |
| ---------------- | ------------------------------------------------------- |
| `--agent <SLUG>` | Agent to operate on; prompted when omitted.             |
| `--session <ID>` | One session id to clear.                                |
| `--all`          | Clear all sessions for the selected agent.              |
| `--super`        | Keep a history barrier instead of deleting the session. |
| `--yes`          | Skip the interactive confirmation.                      |

## repair

Repairs persisted Discord history and refreshes expired media references.

| Option           | Description                                   |
| ---------------- | --------------------------------------------- |
| `--agent <SLUG>` | Agent to repair.                              |
| `--all`          | Repair all agents and their Discord sessions. |

With neither option, `repair` prompts for an agent and session. Both selection prompts support cancellation with Ctrl+C before repair begins.

## codex

Authenticates and manages OpenAI Codex ChatGPT OAuth credentials.

| Option          | Description                                |
| --------------- | ------------------------------------------ |
| `--authId <ID>` | Credential identifier (default `default`). |
| `--logout`      | Delete the stored credentials.             |
| `--status`      | Print the stored account and expiry.       |

Without `--logout` or `--status`, `codex` starts the OAuth flow, opens the authorization URL, and stores the credentials.

## update

Checks and updates the published Linux x64 executable. Use `update check`, `update latest`, `update install [VERSION]`, or `update rollback`; see [Upgrades](../operations/upgrades.md) for repository configuration, mutation locks, and rollback limitations.

`--repository <URL>` overrides the configured Forgejo source for `check`, `latest`, or `install`. `--yes` skips confirmation for `install` or `rollback`. Installation and rollback require a writable published executable and a stopped runtime; they do not restore runtime data or run migrations.

## remote

Administers remote identities and owned sessions. See [Remote sessions](../operations/remote-sessions.md) for setup and examples.

Use `remote OPERATION` with `list`, `inspect`, `invite`, `update-grants`, `revoke`, `revoke-invitations`, `reissue`, `transfer`, or `delete`.

| Option             | Applies to                                                                  |
| ------------------ | --------------------------------------------------------------------------- |
| `--adapter <ID>`   | `inspect`, `update-grants`, `revoke`, `reissue`, `transfer`                 |
| `--session <ID>`   | `inspect`, `transfer`, `delete`                                             |
| `--after <CURSOR>` | `list`, `inspect`; continue a metadata page using its returned `nextCursor` |
| `--grants <PATH>`  | `invite`, `update-grants`; a closed TOML grant record                       |
| `--output <PATH>`  | `invite`, `reissue`; a new private pairing file                             |
| `--endpoint <URL>` | `invite`, `reissue`; the adapter-facing WSS endpoint ending in `/remote/v2` |
| `--yes`            | Skip confirmation for destructive administration                            |

Options not applicable to the operation are rejected; `inspect` requires exactly one adapter or session selector. Administration contacts the running host through its private local socket, or uses locked offline administration when the host is stopped. `list` and `inspect` instead use metadata-only read-only offline access that never creates or migrates authority state. Their JSON includes current grants, ownership, recovery counts and caller receipts, but never message/tool payloads or credential verifiers. `liveStateAvailable` indicates whether attachment state came from the running host. Secrets are written only to the new output file.