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.