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