<!-- 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.              |

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

## 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 prints the loaded agents after startup without a timestamp prefix for table readability.
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.  |
| `-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.

## 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 and validates every configured agent and prints the validated agent list.

## 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. |

Migrations also run automatically at runtime startup.

## 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.

## 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.