Aller au contenu principal

CLI reference

This document contains the help content for the apollia-os command-line program.

Command Overview:

apollia-os​

Apollia OS CLI binary (apollia-os)

Usage: apollia-os [OPTIONS] <COMMAND>

Subcommands:​
  • start - Start the runtime in foreground
  • stop - Stop a running runtime
  • status - Display runtime and agent status
  • run - Submit a task to an agent and wait for the result
  • agent - Agent management (list, start, stop, show, set, reset, export, status, messages, uninstall, enable, disable, package, logs)
  • a2a - Agent-to-Agent skill discovery and direct invocation
  • task - Task management (list, status, cancel, inspect, resume, approvals)
  • eval - Evaluation harness (run a TOML suite against the runtime, report a JSONL)
  • tools - Native tool governance (list, enable, disable, config, reload, credentials, show, approvals)
  • audit - Audit trail (journal, export, verify, anchor, replay, show)
  • hooks - Lifecycle hooks (list)
  • memory - Memory management
  • llm - LLM backend diagnostics (status, ping, chat, costs, backends, reload)
  • model - Local model file management
  • source - The sources an agent may consult once checked: folders, files, mailboxes, the profile, memory (list, create, delete, inspect)
  • trigger - Trigger management (list, status, fire, enable, disable, logs, reload, create, update, delete)
  • notify - Notification channel management (test, list, logs, create, update, delete, events)
  • stt - Speech-to-Text management (status, transcribe, transcriptions, model, config)
  • onboard - Launch onboarding or re-onboarding on a specific topic
  • permissions - Permission rule management (list, revoke, audit)
  • chat - Interactive chat REPL + persisted session hygiene (list, delete, rename, export)
  • mcp - MCP server management (list, add, remove, show, test, restart, update, raw-config, server)
  • update - Check for and install updates from GitHub Releases
  • package - Agent package archives: build, inspect, preview and install a .apo, and trust publisher keys
  • policy - Organisation policy: create the key, write, sign, verify, show
  • workspace - Workspace inspection and initialization (status, init)
  • review - Automated code or plan review via the apollia-review agent
  • approvals - The decisions waiting for you (pending)
  • batch - Run an agent on every item of a source (run, status, list, accesses, pause, resume, stop, retry, export)
  • workflow - Run the workflows of installed packages (show, run, status, logs, cancel)
  • resilience - Circuit breaker inspection and reset (list, show, reset)
  • plan - Plan domain management (cache: stats, clear, evict)
  • service - Run the runtime as a service of your session (install, uninstall, status)
  • doctor - Diagnose the local Apollia environment (no runtime required)
  • logs - Tail or follow the runtime log file
  • version - Print the binary version (use --json for machine-readable output)
  • connector - Native SaaS connector management (list, accounts, test, revoke)
  • config - Global apollia.toml management (get, set, validate, edit, show)
  • profile - User profile management (show, set, forget, reset, export, import)
  • trace - Print the event-sourced trace of a task
  • digest - Aggregated activity overview (tasks + LLM costs)
  • completions - Generate a shell completion script (bash, zsh, fish, powershell, ...)
  • guide - Short, task-oriented help by theme (chat, governance, audit, ...)
  • do - Map a natural-language request to a command (local model), then run it
  • explain - Explain a command or an error message in plain language (local model)
Options:​

  • --socket <PATH> - Unix socket path (default: the runtime socket under the data directory).

    Accepted but ignored on Windows, which has no Unix socket: the CLI opens the runtime's named pipe, whose name comes from USERNAME.

  • --json - Output machine-readable JSON instead of human-readable text.

    Accepted at any position: before or after the subcommand and its arguments.

  • -q, --quiet - Suppress all non-essential output (only success/error shown).

    When combined with --json, JSON output takes priority.

  • -v, --verbose - Show additional details such as durations and step counts

  • --debug - Enable internal debug logs and ORIA traces on stderr.

    Equivalent to setting RUST_LOG=debug.

  • --no-color - Disable ANSI color codes even when stdout is a TTY

apollia-os start​

Start the runtime in foreground

Usage: apollia-os start [OPTIONS]

Options:​
  • --port <PORT> - TCP port to listen on; overrides [api].port (default: 7771)
  • --config <PATH> - Configuration file to load instead of ~/.apollia/apollia.toml

apollia-os stop​

Stop a running runtime

Usage: apollia-os stop

apollia-os status​

Display runtime and agent status

Usage: apollia-os status

apollia-os run​

Submit a task to an agent and wait for the result.

Use the positional <INPUT> for free-text input. To send a structured payload, pass --input-json '<JSON>' here, which overrides the default text wrapping. To invoke a typed skill by its identifier, use apollia-os a2a invoke <skill_id> --args '<JSON>' instead.

Usage: apollia-os run [OPTIONS] <AGENT_ID> [INPUT]

Arguments:​

  • <AGENT_ID> - Agent identifier

  • <INPUT> - Task input text (ignored when --input-json is provided)

    Default value: ``

Options:​

  • --input-json <JSON> - Raw JSON payload that bypasses the parts:[text] wrapper.

    Use this when the target agent expects a structured input shape (e.g. an AIPInput with data parts, a worker skill envelope, or any custom contract).

  • --stream - Stream task progress in real-time via SSE

  • --detach - Submit the task and return immediately without waiting for the result.

    The task ID is printed so it can be tracked with apollia-os task status <id>.

  • --plan - Pause after plan generation to review and approve the plan before execution. Prompts to approve, reject (with optional feedback), or quit

  • --autonomy <LEVEL> - Autonomy tier for this run (default: assisted).

    Controls the execution budget, memory injection, and verification. Accepted values: assisted, supervised, bounded_autonomous, long_autonomous.

apollia-os agent​

Agent management (list, start, stop, show, set, reset, export, status, messages, uninstall, enable, disable, package, logs)

Usage: apollia-os agent <COMMAND>

Subcommands:​
  • list - List all agents (installed and/or runtime)
  • start - Make a stored agent available again, after agent stop
  • stop - Stop (shutdown) a running agent
  • show - Display detailed information about an agent, with its definition as resolved (package defaults, then your overrides)
  • set - Override one field of an agent's definition; a package update keeps it
  • reset - Go back to the package defaults: remove every override of an agent, or the override of one field. Recorded in the audit journal
  • export - Export an agent created in the interface as a .apo package
  • status - Show a compact runtime-status snapshot for <agent_id>
  • messages - List in-memory A2A messages for <agent_id> (oldest-first within window)
  • uninstall - Uninstall an agent installed on its own, through the runtime
  • enable - Enable an installed agent (will auto-start on boot)
  • disable - Disable an installed agent (will not auto-start on boot)
  • package - List, show and uninstall the installed packages
  • logs - Display recent log lines from a running agent

apollia-os agent list​

List all agents (installed and/or runtime)

Usage: apollia-os agent list [OPTIONS]

Options:​
  • --supports-a2a - Show only A2A-capable agents with their skill descriptors
  • --definitions - List the stored agents as resolved (package definition, then your overrides) instead of the runtime inventory

apollia-os agent start​

Make a stored agent available again, after agent stop.

An agent is available as soon as it is installed and enabled; this is only needed for one that was stopped.

Usage: apollia-os agent start <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier

apollia-os agent stop​

Stop (shutdown) a running agent

Usage: apollia-os agent stop <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier

apollia-os agent show​

Display detailed information about an agent, with its definition as resolved (package defaults, then your overrides)

Usage: apollia-os agent show <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier

apollia-os agent set​

Override one field of an agent's definition; a package update keeps it.

Fields: name, mission, autonomy, planning (never, auto or always) and profile (a profile identifier, see profile list) take one value; examples, access and sources take the whole list, one value per item (none for an empty list). A source is an identifier of source list, profile or memory; the runtime refuses any other. The source profile lets the agent read your profile through ctx.profile: agent set <id> sources profile checks it, a list without it unchecks it, and agent reset --field sources goes back to the package default. Recorded in the audit journal.

Usage: apollia-os agent set <AGENT_ID> <FIELD> [VALUES]...

Arguments:​
  • <AGENT_ID> - Agent identifier
  • <FIELD> - Field to override: name, mission, examples, access, sources, autonomy, planning or profile
  • <VALUES> - The value, or the items of a list

apollia-os agent reset​

Go back to the package defaults: remove every override of an agent, or the override of one field. Recorded in the audit journal

Usage: apollia-os agent reset [OPTIONS] <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier
Options:​
  • --field <FIELD> - Remove only the override of this field
  • --confirm - Skip the interactive confirmation prompt

apollia-os agent export​

Export an agent created in the interface as a .apo package.

Its current values become the defaults of the package. No secret, no memory and no history is exported; the account of a connection stays here and becomes a required connection; an access to another package, agent or workflow is left out and listed. The publisher is the author.name setting, or --publisher. Needs the runtime.

Usage: apollia-os agent export [OPTIONS] <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier
Options:​
  • --sign - Sign the package with the author key, generated in the secret store on the first signature
  • --publisher <NAME> - Publisher name for this export only
  • -o, --output <FILE> - File to write. Default: <id>-<version>.apo in the current folder

apollia-os agent status​

Show a compact runtime-status snapshot for <agent_id>.

Distilled view of agent show focused on online / idle / error state. Useful in poll loops where the full info payload is overkill.

Usage: apollia-os agent status <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier

apollia-os agent messages​

List in-memory A2A messages for <agent_id> (oldest-first within window)

Usage: apollia-os agent messages [OPTIONS] <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier (recipient)
Options:​

  • --limit <N> - Maximum number of messages to display (server-clamped to 100)

    Default value: 20

apollia-os agent uninstall​

Uninstall an agent installed on its own, through the runtime.

Removes its definition, its overrides, its model, its triggers, its environment and its files. Its memory and its history are kept unless asked otherwise. An agent of an installed package goes with its package.

Usage: apollia-os agent uninstall [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Agent name (as declared in manifest)
Options:​
  • --clear-memory - Erase the agent's memory instead of keeping it
  • --clear-history - Erase the agent's history (tasks, batches) instead of keeping it
  • --confirm - Skip the interactive confirmation prompt

apollia-os agent enable​

Enable an installed agent (will auto-start on boot)

Usage: apollia-os agent enable <NAME>

Arguments:​
  • <NAME> - Agent name

apollia-os agent disable​

Disable an installed agent (will not auto-start on boot)

Usage: apollia-os agent disable <NAME>

Arguments:​
  • <NAME> - Agent name

apollia-os agent package​

List, show and uninstall the installed packages

Usage: apollia-os agent package <COMMAND>

Subcommands:​
  • list - List all installed agent packages
  • show - Show details for an installed package
  • uninstall - Uninstall a package and everything it installed, through the runtime

apollia-os agent package list​

List all installed agent packages

Usage: apollia-os agent package list

apollia-os agent package show​

Show details for an installed package

Usage: apollia-os agent package show <NAME>

Arguments:​
  • <NAME> - Package name

apollia-os agent package uninstall​

Uninstall a package and everything it installed, through the runtime.

Removes its agents with their overrides, models and triggers, its workflows and tools, its environments, its files and the MCP servers it brought; the connections it required stay. The memory and the history of its agents are kept unless asked otherwise.

Usage: apollia-os agent package uninstall [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Package name
Options:​
  • --clear-memory - Erase the memory of its agents instead of keeping it
  • --clear-history - Erase the history of its agents and workflows (tasks, batches, workflow runs) instead of keeping it
  • --confirm - Skip the interactive confirmation prompt

apollia-os agent logs​

Display recent log lines from a running agent

Usage: apollia-os agent logs [OPTIONS] <AGENT_ID>

Arguments:​
  • <AGENT_ID> - Agent identifier (name or UUID)
Options:​

  • --last <N> - Number of recent log lines to display

    Default value: 50

  • --follow - Not implemented: refuses with an error naming --last instead

apollia-os a2a​

Agent-to-Agent skill discovery and direct invocation.

Worker agents expose typed skills (not free-text prompts). Use these sub-commands to discover skills (a2a skills) and invoke one with a structured payload (a2a invoke <skill_id> --args '<JSON>').

Usage: apollia-os a2a <COMMAND>

Subcommands:​
  • skills - List every skill exposed by active Worker Agents
  • invoke - Invoke a Worker skill by skill_id with a structured payload

apollia-os a2a skills​

List every skill exposed by active Worker Agents.

Output columns: SKILL_ID · AGENT · NAME · DESCRIPTION. Use --json for the full schemas and examples.

Usage: apollia-os a2a skills

apollia-os a2a invoke​

Invoke a Worker skill by skill_id with a structured payload.

The payload comes from --args '<JSON>', from --args-file <PATH> (use - for stdin), or defaults to {} if neither is supplied. The runtime routes to the worker owning the skill; the caller does not need to know which agent it is.

Usage: apollia-os a2a invoke [OPTIONS] <SKILL_ID>

Arguments:​
  • <SKILL_ID> - Skill identifier (e.g. pdf.read_text)
Options:​
  • --args <JSON> - Structured JSON payload (overrides --args-file)
  • --args-file <PATH> - Read the JSON payload from a file (use - for stdin)
  • --timeout <SECS> - Optional invocation timeout in seconds (default: 120)
  • --caller <NAME> - Caller label surfaced in observability (default: cli)

apollia-os task​

Task management (list, status, cancel, inspect, resume, approvals)

Usage: apollia-os task <COMMAND>

Subcommands:​
  • list - List recent tasks
  • status - Display the status of a specific task
  • cancel - Cancel a running task
  • inspect - Display the full execution plan of an orchestrated task
  • resume - Approve or reject a task pending HITL approval
  • approvals - List the task approvals waiting for a decision

apollia-os task list​

List recent tasks.

With --pending-approval, filters to tasks awaiting HITL approval.

Usage: apollia-os task list [OPTIONS]

Options:​
  • --pending-approval - Show only tasks waiting for human approval (status = input_required)

apollia-os task status​

Display the status of a specific task

Usage: apollia-os task status <TASK_ID>

Arguments:​
  • <TASK_ID> - Task identifier (UUID)

apollia-os task cancel​

Cancel a running task

Usage: apollia-os task cancel [OPTIONS] <TASK_ID>

Arguments:​
  • <TASK_ID> - Task identifier (UUID)
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os task inspect​

Display the full execution plan of an orchestrated task.

Reads directly from ~/.apollia/plans.db, no runtime connection required.

Usage: apollia-os task inspect <ID>

Arguments:​
  • <ID> - Task identifier (UUID)

apollia-os task resume​

Approve or reject a task pending HITL approval.

Exactly one of --approve or --reject must be supplied.

Usage: apollia-os task resume [OPTIONS] <TASK_ID>

Arguments:​
  • <TASK_ID> - Task identifier
Options:​
  • --approve - Approve the pending task, resumes agent execution
  • --reject - Reject the pending task, terminates the task with REJECTED status
  • --reason <REASON> - Human-readable reason for rejection (recommended with --reject)

apollia-os task approvals​

List the task approvals waiting for a decision.

The decisions already taken are in the audit journal (apollia-os audit journal).

Usage: apollia-os task approvals [OPTIONS]

Options:​
  • --pending - Accepted and without effect: the list holds the pending approvals only

apollia-os eval​

Evaluation harness (run a TOML suite against the runtime, report a JSONL)

Usage: apollia-os eval <COMMAND>

Subcommands:​
  • run - Run an eval suite against the running runtime
  • report - Re-print a previously written JSONL as a summary table

apollia-os eval run​

Run an eval suite against the running runtime

Usage: apollia-os eval run [OPTIONS] <SUITE>

Arguments:​
  • <SUITE> - Path to the TOML suite
Options:​
  • --out <OUT> - Write the per-run JSONL here (default: <suite>.results.jsonl)
  • --agent <AGENT> - Default agent for tasks that do not name one

apollia-os eval report​

Re-print a previously written JSONL as a summary table

Usage: apollia-os eval report <JSONL>

Arguments:​
  • <JSONL> - Path to the JSONL produced by eval run

apollia-os tools​

Native tool governance (list, enable, disable, config, reload, credentials, show, approvals)

Usage: apollia-os tools <COMMAND>

Subcommands:​
  • list - Show the status of each native tool (active, backend, credentials)
  • enable - Enable the name tool (clears any disabled flag in governance.db)
  • disable - Disable the name tool (sets enabled = FALSE in governance.db)
  • config - Read or update the [tools.<name>] configuration in apollia.toml
  • reload - Reload the governance snapshot and print the effective state
  • credentials - Manage the encrypted credentials attached to a tool
  • show - Show the descriptor of a tool registered with the runtime
  • approvals - Inspect the HITL queue from the tool registry's side

apollia-os tools list​

Show the status of each native tool (active, backend, credentials)

Usage: apollia-os tools list

apollia-os tools enable​

Enable the name tool (clears any disabled flag in governance.db)

Usage: apollia-os tools enable <NAME>

Arguments:​
  • <NAME> - Canonical name of the native tool

apollia-os tools disable​

Disable the name tool (sets enabled = FALSE in governance.db)

Usage: apollia-os tools disable <NAME>

Arguments:​
  • <NAME> - Canonical name of the native tool

apollia-os tools config​

Read or update the [tools.<name>] configuration in apollia.toml

Usage: apollia-os tools config <COMMAND>

Subcommands:​
  • get - Show the effective configuration of name
  • set - Update a configuration key <tool>.<path> in apollia.toml

apollia-os tools config get​

Show the effective configuration of name

Usage: apollia-os tools config get <NAME>

Arguments:​
  • <NAME> - Native tool name (web_search, web_read, …)

apollia-os tools config set​

Update a configuration key <tool>.<path> in apollia.toml

Usage: apollia-os tools config set <KEY_PATH> <VALUE>

Arguments:​
  • <KEY_PATH> - Dotted key path, e.g. web_search.backend or web_search.brave.timeout_secs
  • <VALUE> - New value (parsed according to the expected type)

apollia-os tools reload​

Reload the governance snapshot and print the effective state

Usage: apollia-os tools reload

apollia-os tools credentials​

Manage the encrypted credentials attached to a tool

Usage: apollia-os tools credentials <COMMAND>

Subcommands:​
  • list - List stored credentials (values masked)
  • set - Store a credential (tool, key) after an interactive masked prompt
  • delete - Delete the credential (tool, key)
  • test - Validate a credential with a live call against the backend it targets

apollia-os tools credentials list​

List stored credentials (values masked)

Usage: apollia-os tools credentials list [TOOL]

Arguments:​
  • <TOOL> - Optional filter on a tool name

apollia-os tools credentials set​

Store a credential (tool, key) after an interactive masked prompt

Usage: apollia-os tools credentials set <TOOL> <KEY>

Arguments:​
  • <TOOL> - Owning tool name, or agent for a secret declared by an agent manifest
  • <KEY> - Logical key name (e.g. brave.api_key, or an agent's hubspot_api_token)

apollia-os tools credentials delete​

Delete the credential (tool, key)

Usage: apollia-os tools credentials delete [OPTIONS] <TOOL> <KEY>

Arguments:​
  • <TOOL> - Owning tool name
  • <KEY> - Logical key name
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os tools credentials test​

Validate a credential with a live call against the backend it targets

Usage: apollia-os tools credentials test <TOOL>

Arguments:​
  • <TOOL> - Tool whose credentials should be checked

apollia-os tools show​

Show the descriptor of a tool registered with the runtime

Usage: apollia-os tools show <TOOL_NAME>

Arguments:​
  • <TOOL_NAME> - Tool name

apollia-os tools approvals​

Inspect the HITL queue from the tool registry's side

Usage: apollia-os tools approvals <COMMAND>

Subcommands:​
  • pending - List approvals pending decision (tasks in input_required)

apollia-os tools approvals pending​

List approvals pending decision (tasks in input_required)

Usage: apollia-os tools approvals pending

apollia-os audit​

Audit trail (journal, export, verify, anchor, replay, show)

Usage: apollia-os audit <COMMAND>

Subcommands:​
  • journal - Browse the hash-chained journal across every run, newest first
  • export - Export the hash-chained journal to a file, as CSV or JSON
  • verify - Verify the audit journal's hash chains and signatures
  • anchor - Print the exportable head anchor of the global chain
  • replay - Check that the captured trace of a run is complete and consistent
  • show - Show a run's full journal, including the model's LLM completions

apollia-os audit journal​

Browse the hash-chained journal across every run, newest first.

Unlike audit show RUN (one run), this reads the chained journal without needing a run id up front, so the audited register is reachable by browsing. Each entry is printed as its summary: when, who, what, on what, with which result, and never the content of a call. The filters add up, and --limit and --offset count the entries that pass them.

Usage: apollia-os audit journal [OPTIONS]

Options:​

  • --limit <LIMIT> - Maximum number of entries to display

    Default value: 20

  • --offset <OFFSET> - Number of entries to skip, newest first. Page through with it

    Default value: 0

  • --agent <AGENT> - Keep what names this agent, and the runs of its tasks. Repeat it for several agents

  • --family <FAMILY> - Keep this action family: read, read_personal, write_or_delete, send_external, execute_code. Repeat it for several

  • --nature <NATURE> - Keep this nature: action, access_change, policy, system. Repeat it for several

  • --result <RESULT> - Keep this result: success, failure, refused. Repeat it for several

  • --since <DATE> - Start of the period, included: YYYY-MM-DD (UTC) or an RFC 3339 instant

  • --until <DATE> - End of the period, excluded: YYYY-MM-DD (UTC) or an RFC 3339 instant

apollia-os audit export​

Export the hash-chained journal to a file, as CSV or JSON.

The file holds every entry that passes the filters, newest first, each as its summary: when, who, what, on what, with which result, and its place in the chain. --detail adds the payload of each entry and the arguments and output of each tool call, which may hold personal data. The filters are those of audit journal. The file is written on this machine, and the export is itself recorded in the journal.

Usage: apollia-os audit export [OPTIONS] --format <FORMAT> --output <PATH>

Options:​

  • --format <FORMAT> - Format of the file

    Possible values:

    • csv: Comma-separated values, UTF-8, one header row
    • json: One JSON document with the entries

  • --detail - Add the detail of each entry: its payload, and the arguments and output of its tool call. May hold personal data

  • --agent <AGENT> - Keep what names this agent, and the runs of its tasks. Repeat it for several agents

  • --family <FAMILY> - Keep this action family: read, read_personal, write_or_delete, send_external, execute_code. Repeat it for several

  • --nature <NATURE> - Keep this nature: action, access_change, policy, system. Repeat it for several

  • --result <RESULT> - Keep this result: success, failure, refused. Repeat it for several

  • --since <DATE> - Start of the period, included: YYYY-MM-DD (UTC) or an RFC 3339 instant

  • --until <DATE> - End of the period, excluded: YYYY-MM-DD (UTC) or an RFC 3339 instant

  • --output <PATH> - File the export is written to

apollia-os audit verify​

Verify the audit journal's hash chains and signatures.

With a RUN_ID, verifies that run's per-run chain. Without an argument, verifies the whole journal: the global chain across all runs (detecting interior deletion and whole-run deletion) and the head anchor (detecting truncation of the global tail).

Usage: apollia-os audit verify [RUN_ID]

Arguments:​
  • <RUN_ID> - Identifier of the run to verify. Omit to verify the whole journal

apollia-os audit anchor​

Print the exportable head anchor of the global chain.

Storing this off-machine is the only defense against truncation of the global tail once the signing key can be compromised.

Usage: apollia-os audit anchor

apollia-os audit replay​

Check that the captured trace of a run is complete and consistent.

Steps through the trace the journal captured, offline: each model response is read back, and each tool call it asked for is matched with the tool output captured next, as are the changes of the plan. No model is called, no tool runs and the agent is not run again: this tells whether the trace holds together, not whether the agent would answer the same today. Divergences are grouped by category in the human output and listed in the --json payload. run accepts a full run_id or an unambiguous prefix of at least 8 characters. Exit 0 = identical, exit 2 = diverged, exit 1 = any error (run not found, ambiguous prefix, incomplete trace, runtime unreachable).

Usage: apollia-os audit replay <RUN>

Arguments:​
  • <RUN> - Run identifier or unambiguous prefix

apollia-os audit show​

Show a run's full journal, including the model's LLM completions.

Reads the hash-chained journal, so the captured reasoning (prompts/responses) is readable. Accepts a run_id or a task_id (resolved to its run_id).

Usage: apollia-os audit show <RUN_OR_TASK>

Arguments:​
  • <RUN_OR_TASK> - Run identifier, or a task_id that maps to one

apollia-os hooks​

Lifecycle hooks (list)

Usage: apollia-os hooks <COMMAND>

Subcommands:​
  • list - List the registered lifecycle hook handlers

apollia-os hooks list​

List the registered lifecycle hook handlers

Usage: apollia-os hooks list [OPTIONS]

Options:​
  • --dry-run - Read configuration from apollia.toml and validate it without connecting to the runtime

apollia-os memory​

Memory management

Usage: apollia-os memory <COMMAND>

Subcommands:​
  • inspect - Inspect the state of a memory namespace
  • list - List every memory namespace present on disk
  • clear - Wipe an agent's memory
  • purge - Purge memory entries older than a day threshold
  • learn-procedure - Record a procedure in a namespace's procedural memory
  • export - Export a namespace's memory to a JSON file
  • import - Import memory from a JSON file into a namespace
  • forget - Delete a single memory entry by its UUID
  • search - Full-text search across a namespace's episodic + semantic memory

apollia-os memory inspect​

Inspect the state of a memory namespace

Usage: apollia-os memory inspect [OPTIONS] <NAMESPACE>

Arguments:​
  • <NAMESPACE> - Namespace name to inspect
Options:​
  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)
  • --json - JSON output

apollia-os memory list​

List every memory namespace present on disk

Usage: apollia-os memory list [OPTIONS]

Options:​
  • --agent <NAME> - Filter by agent/namespace name
  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

apollia-os memory clear​

Wipe an agent's memory

Usage: apollia-os memory clear [OPTIONS] --agent <NAME>

Options:​

  • --agent <NAME> - Namespace/agent name to wipe

  • --type <TYPE> - Memory type to wipe

    Default value: all

    Possible values:

    • episodic: Episodic memories
    • semantic: Semantic memories
    • procedural: Procedural memories
    • all: All memory types

  • --confirm - Confirm without an interactive prompt

  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

apollia-os memory purge​

Purge memory entries older than a day threshold.

Example: apollia-os memory purge --namespace my-agent --older-than 30 Filtered: apollia-os memory purge --namespace my-agent --type episodic --older-than 7

Usage: apollia-os memory purge [OPTIONS] --namespace <NAME> --older-than <DAYS>

Options:​

  • --namespace <NAME> - Target namespace

  • --older-than <DAYS> - Delete entries created more than N days ago

  • --type <TYPE> - Restrict the purge to a single type (default: all types)

    Possible values:

    • episodic: Episodic memories
    • semantic: Semantic memories
    • procedural: Procedural memories
    • all: All memory types

  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

  • --confirm - Skip the interactive confirmation prompt

apollia-os memory learn-procedure​

Record a procedure in a namespace's procedural memory.

Example: apollia-os memory learn-procedure --namespace agent-x --trigger "analyse a report" --steps "1. Open, 2. Read, 3. Summarise"

Usage: apollia-os memory learn-procedure [OPTIONS] --namespace <NAME> --trigger <TEXT>

Options:​
  • --namespace <NAME> - Target namespace
  • --trigger <TEXT> - Exact trigger phrase for the procedure
  • --steps <STEPS> - Procedure steps (comma- or semicolon-separated). Example: "Open the PDF, Extract revenue, Generate summary"
  • --file <FILE> - JSON file containing {"trigger": "...", "steps": [...]}
  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

apollia-os memory export​

Export a namespace's memory to a JSON file.

Example: apollia-os memory export --namespace agent-x --output ./backup.apollia-memory

Usage: apollia-os memory export [OPTIONS] --namespace <NAME>

Options:​
  • --namespace <NAME> - Namespace to export
  • --output <FILE> - Output file (default: <namespace>.apollia-memory in the current directory)
  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

apollia-os memory import​

Import memory from a JSON file into a namespace.

Example: apollia-os memory import --namespace agent-x --input ./backup.apollia-memory --replace

Usage: apollia-os memory import [OPTIONS] --namespace <NAME> --input <FILE>

Options:​
  • --namespace <NAME> - Target namespace
  • --input <FILE> - Input file exported by memory export
  • --replace - Mode: replace the existing namespace (default: merge)
  • --merge - Mode: merge with the existing namespace (default)
  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

apollia-os memory forget​

Delete a single memory entry by its UUID.

Searches episodic_memories, semantic_memories, and procedural_memories in order; removes the matching row and its FTS5 index entry. Returns exit 1 when no entry matches.

Usage: apollia-os memory forget [OPTIONS] <NAMESPACE> <ENTRY_ID>

Arguments:​
  • <NAMESPACE> - Namespace containing the entry
  • <ENTRY_ID> - Entry UUID (matches id columns across the three tables)
Options:​
  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)
  • --confirm - Skip the interactive confirmation prompt

Full-text search across a namespace's episodic + semantic memory.

Returns BM25-ranked matches with their source table (episodic|semantic), content, and relevance score.

Usage: apollia-os memory search [OPTIONS] <NAMESPACE> <QUERY>

Arguments:​
  • <NAMESPACE> - Namespace to search
  • <QUERY> - FTS5 query (whitespace-separated keywords; quotes preserved)
Options:​

  • --limit <N> - Maximum number of matches to return

    Default value: 20

  • --source <SOURCE> - Restrict to a single source: episodic or semantic. Omit for both

    Possible values: episodic, semantic

  • --data-dir <DIR> - Memory data directory (default: ~/.apollia/memory/)

apollia-os llm​

LLM backend diagnostics (status, ping, chat, costs, backends, reload)

Usage: apollia-os llm <COMMAND>

Subcommands:​
  • status - Display the status of all configured LLM backends
  • ping - Measure the latency of a specific LLM backend
  • chat - Send a direct prompt to an LLM backend and print the response
  • costs - Display aggregated usage and costs (tokens and estimated cost per backend)
  • backends - Manage configured LLM backends (list, create, update, delete, set-default)
  • reload - Reload the LLM router from system.db without restarting the runtime
  • setup - First-run helper: configure a local LLM in one step

apollia-os llm status​

Display the status of all configured LLM backends

Usage: apollia-os llm status

apollia-os llm ping​

Measure the latency of a specific LLM backend

Usage: apollia-os llm ping [BACKEND]

Arguments:​
  • <BACKEND> - Backend name (default: the router's configured default backend)

apollia-os llm chat​

Send a direct prompt to an LLM backend and print the response

Usage: apollia-os llm chat [OPTIONS] <PROMPT>

Arguments:​
  • <PROMPT> - The prompt text to send to the LLM
Options:​
  • --backend <BACKEND> - Backend to use (optional, uses the configured default if omitted)

apollia-os llm costs​

Display aggregated usage and costs (tokens and estimated cost per backend)

Usage: apollia-os llm costs

apollia-os llm backends​

Manage configured LLM backends (list, create, update, delete, set-default)

Usage: apollia-os llm backends <COMMAND>

Subcommands:​
  • list - List all configured LLM backends
  • show - Show the full configuration of a backend (including config_json)
  • create - Create a new LLM backend
  • update - Update an existing LLM backend
  • delete - Delete an LLM backend
  • set-default - Set a backend as the default backend

apollia-os llm backends list​

List all configured LLM backends

Usage: apollia-os llm backends list

apollia-os llm backends show​

Show the full configuration of a backend (including config_json)

Usage: apollia-os llm backends show <NAME>

Arguments:​
  • <NAME> - Backend name

apollia-os llm backends create​

Create a new LLM backend.

--provider drives the shape of the config_json sent to the runtime. For llama-cpp (local GGUF models), --model must be the absolute path to the .gguf file. For an OpenAI-compatible server or Ollama, --model is the identifier the server knows (e.g. qwen3-32b).

Usage: apollia-os llm backends create [OPTIONS] --provider <PROVIDER> --model <MODEL> <NAME>

Arguments:​
  • <NAME> - Unique backend name (snake_case or kebab-case)
Options:​

  • --provider <PROVIDER> - Provider: llama-cpp (local GGUF), openai (any OpenAI-compatible server, designated by --base-url), ollama. Any other value is refused. --kind is accepted as an alias for backward compatibility

  • --model <MODEL> - Model identifier or path (absolute path for llama-cpp)

  • --api-key <KEY> - API key of the server, when it requires one. The runtime moves it into the secret store before saving the backend: config_json keeps only api_key_in_store, never the key

  • --api-key-env <VAR_NAME> - Environment variable name holding the API key.

    The runtime reads std::env::var(NAME) at boot; only the variable name is saved.

  • --base-url <URL> - Base URL (Ollama, self-hosted OpenAI-compatible gateway, ...)

  • --device <DEVICE> - Device recorded on the backend row: metal, cuda, cpu.

    It selects nothing today. The local engine offloads according to the llama-server build it ships with and to APOLLIA_LLAMA_N_GPU_LAYERS, and reads no device field.

    Default value: metal

  • --timeout-sec <SECS> - How long the backend may stay silent before the call is abandoned.

    This is a backstop against a wedged backend, not a latency policy. On the non-streaming path a server sends nothing until generation is complete, so this budget has to cover the slowest honest answer: a large model on modest hardware legitimately takes minutes. Values below 60 seconds are raised to 60.

    Default value: 600

  • --context-window <TOKENS> - Usable context window of this backend, in tokens.

    Sizes conversation compaction. A self-hosted OpenAI-compatible server does not report its window, so without this the runtime falls back to a generic limit that can exceed what the server loaded. On an Ollama backend this is the window requested from Ollama on every call; left unset, 32768 tokens or the model's trained length if shorter, rather than Ollama's own memory-based default.

  • --disabled - Create the backend disabled

  • --default - Mark this backend as the default (only one at a time)

apollia-os llm backends update​

Update an existing LLM backend.

Works in merge mode: flags that are not supplied keep their current value. The runtime exposes PUT as replace, so the CLI fetches the existing config first and only overwrites the fields the operator changed.

Usage: apollia-os llm backends update [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Backend name to update
Options:​
  • --provider <PROVIDER> - New provider (rarely useful, changes the backend implementation): llama-cpp, openai or ollama
  • --model <MODEL> - New model (absolute path for llama-cpp)
  • --api-key <KEY> - New API key of the server
  • --api-key-env <VAR_NAME> - New environment variable name for the API key
  • --base-url <URL> - New base URL
  • --device <DEVICE> - New device recorded on the backend row. It selects nothing today: the local engine offloads according to the llama-server build it ships with and to APOLLIA_LLAMA_N_GPU_LAYERS
  • --timeout-sec <SECS> - New inference timeout in seconds
  • --enable - Enable the backend
  • --disable - Disable the backend
  • --default - Mark as default

apollia-os llm backends delete​

Delete an LLM backend

Usage: apollia-os llm backends delete [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Backend name to delete
Options:​
  • --confirm - Confirm deletion without an interactive prompt

apollia-os llm backends set-default​

Set a backend as the default backend

Usage: apollia-os llm backends set-default <NAME>

Arguments:​
  • <NAME> - Backend name to mark as default

apollia-os llm reload​

Reload the LLM router from system.db without restarting the runtime.

backends create/update/delete/set-default write to the database but the in-memory router stays frozen until a reload. This command swaps the active router in place without interrupting running tasks.

Usage: apollia-os llm reload

apollia-os llm setup​

First-run helper: configure a local LLM in one step.

--local is the only mode supported today. It expects a .gguf model path, copies it into ~/.apollia/models/ (no copy when already there), and creates a backend named local with provider=llama-cpp and is_default=true in system.db. The runtime picks the new default on the next llm reload (or daemon restart).

Usage: apollia-os llm setup [OPTIONS] --model <PATH>

Options:​

  • --local - Use the local llama-cpp backend (required: a server elsewhere is declared with llm backends create --base-url)

  • --model <PATH> - Path to the .gguf model file

  • --name <NAME> - Backend name (default: local). Overwrites the existing entry of the same name

    Default value: local

  • --device <DEVICE> - Device hint recorded on the backend row: metal, cuda, cpu. When omitted, records metal on macOS and cpu elsewhere.

    It selects nothing today. The local engine offloads according to the llama-server build it ships with and to APOLLIA_LLAMA_N_GPU_LAYERS, and reads no device field.

  • --system-db <PATH> - Override the system database path (default: ~/.apollia/system.db)

  • --models-dir <DIR> - Override the models directory. Without it, [models] dir of apollia.toml, else ~/.apollia/models/

apollia-os model​

Local model file management

Usage: apollia-os model <COMMAND>

Subcommands:​
  • list - List available .gguf model files in ~/.apollia/models/
  • search - Search the HuggingFace registry through the runtime
  • show - Fetch metadata + file list for a HuggingFace model
  • hardware - Report the runtime's detected hardware profile (RAM, CPU, GPU)
  • recommend - Rank the models this machine should run
  • embeddings - The embeddings model search by meaning uses
  • delete - Remove a local model file from ~/.apollia/models/

apollia-os model list​

List available .gguf model files in ~/.apollia/models/

Usage: apollia-os model list

Search the HuggingFace registry through the runtime

Usage: apollia-os model search [OPTIONS] <QUERY>

Arguments:​
  • <QUERY> - Free-text query (matches model id, description, tags)
Options:​

  • --limit <LIMIT> - Maximum number of hits to return (default: 20)

    Default value: 20

apollia-os model show​

Fetch metadata + file list for a HuggingFace model

Usage: apollia-os model show <REPO>

Arguments:​
  • <REPO> - Repository identifier in org/repo form

apollia-os model hardware​

Report the runtime's detected hardware profile (RAM, CPU, GPU)

Usage: apollia-os model hardware

apollia-os model recommend​

Rank the models this machine should run

Usage: apollia-os model recommend [OPTIONS]

Options:​

  • --limit <LIMIT> - Maximum number of recommendations to show

    Default value: 5

  • --n-ctx <N_CTX> - Context window the memory estimate is sized against, in tokens.

    Defaults to what the runtime launches with. Lower it to see the larger models that then fit.

apollia-os model embeddings​

The embeddings model search by meaning uses

Usage: apollia-os model embeddings <COMMAND>

Subcommands:​
  • show - Show the default embeddings model, and whether its file is installed
  • set-default - Set the default embeddings model, by its registry identifier

apollia-os model embeddings show​

Show the default embeddings model, and whether its file is installed

Usage: apollia-os model embeddings show

apollia-os model embeddings set-default​

Set the default embeddings model, by its registry identifier

Usage: apollia-os model embeddings set-default <MODEL>

Arguments:​
  • <MODEL> - Identifier of an embeddings entry of the registry, as GET /api/v1/llm/embeddings lists them (for example multilingual-e5-small)

apollia-os model delete​

Remove a local model file from ~/.apollia/models/

Usage: apollia-os model delete [OPTIONS] <NAME>

Arguments:​
  • <NAME> - File name relative to the models directory
Options:​
  • --confirm - Skip the confirmation prompt

apollia-os source​

The sources an agent may consult once checked: folders, files, mailboxes, the profile, memory (list, create, delete, inspect)

Usage: apollia-os source <COMMAND>

Subcommands:​
  • list - List the sources, oldest first
  • create - Add a source
  • delete - Remove a source. Agents that list it stop seeing it
  • inspect - Preview a workbook or a CSV file as a batch would read it: the sheet and header row proposed, the first twenty rows, the columns
  • report - Show the report of the migration of the former projects into sources: what each project became, and what could not be carried over

apollia-os source list​

List the sources, oldest first

Usage: apollia-os source list

apollia-os source create​

Add a source

Usage: apollia-os source create [OPTIONS] --kind <KIND> --label <LABEL>

Options:​
  • --kind <KIND> - What the source is: folder, file, mail, profile, memory or code_folder
  • --label <LABEL> - The name the user sees
  • --reference <REFERENCE> - What the source points at: a folder connection, a file path, a mail connection, a memory space. Required for folder, file and mail
  • --group <GROUP> - A group the source belongs to, such as the files of one project

apollia-os source delete​

Remove a source. Agents that list it stop seeing it

Usage: apollia-os source delete [OPTIONS] <ID>

Arguments:​
  • <ID> - Source identifier, as source list shows it
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os source inspect​

Preview a workbook or a CSV file as a batch would read it: the sheet and header row proposed, the first twenty rows, the columns

Usage: apollia-os source inspect [OPTIONS] <FILE>

Arguments:​
  • <FILE> - The .xlsx, .xlsm, .xlsb, .xls, .ods or .csv file
Options:​
  • --sheet <SHEET> - Show this sheet instead of the proposed one
  • --header-row <HEADER_ROW> - Read the header on this row (from 1) instead of the proposed one

apollia-os source report​

Show the report of the migration of the former projects into sources: what each project became, and what could not be carried over

Usage: apollia-os source report

apollia-os trigger​

Trigger management (list, status, fire, enable, disable, logs, reload, create, update, delete)

Usage: apollia-os trigger <COMMAND>

Subcommands:​
  • list - List all triggers with their status
  • status - Show the detailed status of a trigger
  • fire - Fire a trigger immediately (debug/test)
  • enable - Enable a disabled trigger
  • disable - Disable a trigger without editing apollia.toml
  • logs - Show the firing history from SQLite
  • reload - Reload trigger config from apollia.toml (hot reload)
  • create - Create a new trigger (CRUD, complements hot-reload via apollia.toml)
  • update - Update an existing trigger
  • delete - Delete a trigger

apollia-os trigger list​

List all triggers with their status

Usage: apollia-os trigger list

apollia-os trigger status​

Show the detailed status of a trigger

Usage: apollia-os trigger status <ID>

Arguments:​
  • <ID> - Trigger identifier

apollia-os trigger fire​

Fire a trigger immediately (debug/test)

Usage: apollia-os trigger fire <ID>

Arguments:​
  • <ID> - Trigger identifier

apollia-os trigger enable​

Enable a disabled trigger

Usage: apollia-os trigger enable <ID>

Arguments:​
  • <ID> - Trigger identifier

apollia-os trigger disable​

Disable a trigger without editing apollia.toml

Usage: apollia-os trigger disable <ID>

Arguments:​
  • <ID> - Trigger identifier

apollia-os trigger logs​

Show the firing history from SQLite

Usage: apollia-os trigger logs [OPTIONS] <ID>

Arguments:​
  • <ID> - Trigger identifier
Options:​

  • --last <LAST> - Maximum number of entries to display

    Default value: 20

apollia-os trigger reload​

Reload trigger config from apollia.toml (hot reload).

Rereads [[triggers]] from apollia.toml, validates the new definitions, and restarts modified sources. Invalid TOML or invalid trigger configuration returns an error without interrupting the currently-running triggers.

Usage: apollia-os trigger reload

apollia-os trigger create​

Create a new trigger (CRUD, complements hot-reload via apollia.toml)

Usage: apollia-os trigger create [OPTIONS] --agent <AGENT> --kind <TYPE> <ID>

Arguments:​
  • <ID> - Unique trigger identifier
Options:​

  • --agent <AGENT> - Target agent

  • --kind <TYPE> - Source type: cron, interval, oneshot, filewatch, webhook

  • --detail <DETAIL> - Source-specific detail: cron → cron expression (e.g. "0 9 * * 1") interval → duration string (30m, 1h, 6h, 1d) oneshot → RFC 3339 timestamp filewatch → path to a file or directory webhook → shared HMAC-SHA256 secret of at least 32 chars

  • --on-busy <ON_BUSY> - Policy when the agent is busy when a fire arrives. queue enqueues the fire (default), drop discards it

    Default value: queue

    Possible values: queue, drop

  • --input <INPUT> - Input template sent to the agent when fired

apollia-os trigger update​

Update an existing trigger

Usage: apollia-os trigger update [OPTIONS] <ID>

Arguments:​
  • <ID> - Trigger identifier
Options:​

  • --detail <DETAIL> - New source detail (kind is read from the existing definition)

  • --on-busy <ON_BUSY> - New on-busy policy (queue or drop)

    Possible values: queue, drop

  • --input <INPUT> - New input template

apollia-os trigger delete​

Delete a trigger

Usage: apollia-os trigger delete [OPTIONS] <ID>

Arguments:​
  • <ID> - Trigger identifier
Options:​
  • --confirm - Confirm deletion without an interactive prompt

apollia-os notify​

Notification channel management (test, list, logs, create, update, delete, events)

Usage: apollia-os notify <COMMAND>

Subcommands:​
  • test - Send a test notification to every active channel
  • list - List configured notification channels with their status
  • logs - Show the recent notification history from SQLite
  • create - Create a new notification channel
  • update - Update an existing notification channel
  • delete - Delete a notification channel
  • events - Show or modify the event types that trigger notifications

apollia-os notify test​

Send a test notification to every active channel.

Asks the runtime to dispatch a test payload to each channel enabled in apollia.toml. Exits 0 if every active channel succeeds, 1 if any channel returns an error.

Usage: apollia-os notify test

apollia-os notify list​

List configured notification channels with their status.

Shows the identifier, type, accepted events and state (enabled / disabled) for each channel declared in apollia.toml.

Usage: apollia-os notify list

apollia-os notify logs​

Show the recent notification history from SQLite.

Reads the notification_logs table in ~/.apollia/hitl.db. Returns an empty list if the table does not exist yet.

Usage: apollia-os notify logs [OPTIONS]

Options:​

  • --last <LAST> - Number of lines to display (default: 20)

    Default value: 20

apollia-os notify create​

Create a new notification channel

Usage: apollia-os notify create [OPTIONS] --kind <TYPE>

Options:​

  • --kind <TYPE> - Channel type: desktop or webhook

    Possible values: desktop, webhook

  • --url <URL> - Target URL (required for webhook)

  • --id <ID> - Channel identifier. Auto-generated as <kind>-<timestamp> when omitted (operator-friendly default for ad-hoc creation)

  • --label <TEXT> - Human-readable label shown in the UI. Defaults to the id

  • --disabled - Create the channel disabled (default: enabled)

apollia-os notify update​

Update an existing notification channel

Usage: apollia-os notify update [OPTIONS] <ID>

Arguments:​
  • <ID> - Channel identifier
Options:​

  • --url <URL> - New URL (for webhook)

  • --enabled <ENABLED> - Enable or disable

    Possible values: true, false

apollia-os notify delete​

Delete a notification channel

Usage: apollia-os notify delete [OPTIONS] <ID>

Arguments:​
  • <ID> - Channel identifier
Options:​
  • --confirm - Confirm without an interactive prompt

apollia-os notify events​

Show or modify the event types that trigger notifications

Usage: apollia-os notify events <COMMAND>

Subcommands:​
  • get - Show the configured event types
  • set - Set the active event types (comma-separated list)

apollia-os notify events get​

Show the configured event types

Usage: apollia-os notify events get

apollia-os notify events set​

Set the active event types (comma-separated list)

Usage: apollia-os notify events set [EVENT]...

Arguments:​
  • <EVENT> - Enabled event types (e.g. task_completed,task_failed,agent_error)

apollia-os stt​

Speech-to-Text management (status, transcribe, transcriptions, model, config)

Usage: apollia-os stt <COMMAND>

Subcommands:​
  • status - Display the STT engine status (enabled, model, backend, acceleration)
  • transcribe - Transcribe an audio file and print the resulting text
  • transcriptions - List recent transcriptions from the local database
  • model - Manage local STT model files
  • config - Manage STT configuration (backend, model, language)

apollia-os stt status​

Display the STT engine status (enabled, model, backend, acceleration)

Usage: apollia-os stt status

apollia-os stt transcribe​

Transcribe an audio file and print the resulting text

Usage: apollia-os stt transcribe [OPTIONS] <FILE>

Arguments:​
  • <FILE> - Path to the audio file (WAV format)
Options:​
  • --output <PATH> - Save the full TranscriptResult to a JSON file instead of stdout

apollia-os stt transcriptions​

List recent transcriptions from the local database

Usage: apollia-os stt transcriptions <COMMAND>

Subcommands:​
  • list - List recent transcriptions
  • delete - Delete a transcription by its ID

apollia-os stt transcriptions list​

List recent transcriptions

Usage: apollia-os stt transcriptions list [OPTIONS]

Options:​

  • --limit <LIMIT> - Maximum number of entries to display

    Default value: 20

apollia-os stt transcriptions delete​

Delete a transcription by its ID

Usage: apollia-os stt transcriptions delete [OPTIONS] <ID>

Arguments:​
  • <ID> - Transcription identifier
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os stt model​

Manage local STT model files

Usage: apollia-os stt model <COMMAND>

Subcommands:​
  • list - List .bin model files in ~/.apollia/models/
  • download - Download a model from HuggingFace

apollia-os stt model list​

List .bin model files in ~/.apollia/models/

Usage: apollia-os stt model list

apollia-os stt model download​

Download a model from HuggingFace

Usage: apollia-os stt model download <NAME>

Arguments:​
  • <NAME> - Model name (e.g. whisper-large-v3-fr-q5_0)

apollia-os stt config​

Manage STT configuration (backend, model, language)

Usage: apollia-os stt config <COMMAND>

Subcommands:​
  • get - Show the current STT configuration
  • update - Update the STT configuration

apollia-os stt config get​

Show the current STT configuration

Usage: apollia-os stt config get

apollia-os stt config update​

Update the STT configuration

Usage: apollia-os stt config update [OPTIONS]

Options:​
  • --backend <BACKEND> - Backend to use (whisper, disabled)
  • --model-path <MODEL_PATH> - Path to the Whisper model
  • --language <LANGUAGE> - Language (fr, en, auto)

apollia-os onboard​

Launch onboarding or re-onboarding on a specific topic

Usage: apollia-os onboard [OPTIONS]

Options:​
  • --topic <TOPIC> - Focus on a specific topic (identity, preferences, tools, domain, agents)

apollia-os permissions​

Permission rule management (list, revoke, audit)

Usage: apollia-os permissions <COMMAND>

Subcommands:​
  • list - List persisted rules, for one agent and for every agent
  • revoke - Revoke a rule by identifier, or every matching rule with --all
  • add - Add a persisted permission rule for a tool + optional argument prefix

apollia-os permissions list​

List persisted rules, for one agent and for every agent

Usage: apollia-os permissions list [OPTIONS]

Options:​
  • --scope <SCOPE> - Filter by scope: agent or global
  • --tool <TOOL> - Filter by tool name

apollia-os permissions revoke​

Revoke a rule by identifier, or every matching rule with --all

Usage: apollia-os permissions revoke [OPTIONS] [ID]

Arguments:​
  • <ID> - Numeric identifier of a persisted rule
Options:​
  • --all - Revoke every rule matching --scope
  • --scope <SCOPE> - Scope targeted by --all: agent or global
  • --yes - Skip the interactive confirmation (useful for scripts)

apollia-os permissions add​

Add a persisted permission rule for a tool + optional argument prefix.

Persists into governance.db directly (no runtime required). The rule applies to one agent (--scope agent --agent <ID>) or to every agent (--scope global).

Usage: apollia-os permissions add [OPTIONS] --tool <NAME>

Options:​

  • --tool <NAME> - Tool name (e.g. file_write, bash_executor)

  • --prefix <PREFIX> - Optional argument prefix the rule applies to (e.g. a path). When omitted, the rule pre-authorizes any invocation of --tool, except for code executors (bash_executor, python_executor), which are never blanket-authorized. With a prefix, the rule is evaluated on every invocation against the call's argument; for a code executor it only ever covers a single simple command (no chaining, pipe, redirection or substitution)

  • --action <ACTION> - Rule action: allow or deny

    Default value: allow

    Possible values: allow, deny

  • --scope <SCOPE> - Rule scope: agent (one agent) or global (every agent)

    Default value: global

    Possible values: agent, global

  • --agent <ID> - Agent the rule applies to (required when --scope agent)

apollia-os chat​

Interactive chat REPL + persisted session hygiene (list, delete, rename, export).

Without a subcommand: launches the REPL (resume with --resume <id>, or list recent sessions with --list). With a subcommand: operates on ~/.apollia/chat.db directly; no runtime required.

Usage: apollia-os chat [OPTIONS] [COMMAND]

Subcommands:​
  • list - List the persisted chat sessions, each with the folder it is in
  • delete - Delete a persisted chat session and all of its messages, for good
  • rename - Set the user-defined title of a persisted chat session
  • export - Export a persisted chat session to a file
  • capabilities - Show what the model of a chat session can do: the reasoning setting it offers (none, on or off, or a level) and whether it reads images
  • template - Show the prompt template the model of a chat session receives: the one its preset carries, else the one the local engine reports for the loaded model
  • settings - Read or replace what one conversation changes from its agent: its request settings, its instructions, the accesses it switches off
  • notes - Read or replace the notes kept beside one conversation
  • config - Manage the Chat Libre configuration (system prompt, allowed tools, backend)
Options:​
  • --resume <SESSION_ID> - Resume an existing session from its last message
  • --list - List the 10 most recent sessions

apollia-os chat list​

List the persisted chat sessions, each with the folder it is in.

Reads the chat database, no runtime required. A session the desktop application sent to its trash is not listed.

Usage: apollia-os chat list [OPTIONS]

Options:​
  • --db <PATH> - Override the chat database path (default: ~/.apollia/chat.db)

apollia-os chat delete​

Delete a persisted chat session and all of its messages, for good.

Nothing goes to the trash of the desktop application: a session deleted here cannot be restored. A session already in that trash is erased the same way.

Usage: apollia-os chat delete [OPTIONS] <SESSION_ID>

Arguments:​
  • <SESSION_ID> - Session id (8+ char ulid-like string returned by chat --list)
Options:​
  • --confirm - Skip the interactive confirmation prompt
  • --db <PATH> - Override the chat database path (default: ~/.apollia/chat.db)

apollia-os chat rename​

Set the user-defined title of a persisted chat session

Usage: apollia-os chat rename [OPTIONS] <SESSION_ID> <TITLE>

Arguments:​
  • <SESSION_ID> - Session id
  • <TITLE> - New title (max 100 chars, leading/trailing whitespace trimmed)
Options:​
  • --db <PATH> - Override the chat database path

apollia-os chat export​

Export a persisted chat session to a file

Usage: apollia-os chat export [OPTIONS] <SESSION_ID>

Arguments:​
  • <SESSION_ID> - Session id
Options:​

  • --output <PATH> - Output file path. Defaults to stdout when omitted

  • --format <FORMAT> - Output format: markdown (default) or json

    Default value: markdown

    Possible values: markdown, json

  • --db <PATH> - Override the chat database path

apollia-os chat capabilities​

Show what the model of a chat session can do: the reasoning setting it offers (none, on or off, or a level) and whether it reads images.

Reaches the runtime; exits 2 when it is not running.

Usage: apollia-os chat capabilities <SESSION_ID>

Arguments:​
  • <SESSION_ID> - Session id

apollia-os chat template​

Show the prompt template the model of a chat session receives: the one its preset carries, else the one the local engine reports for the loaded model.

Reaches the runtime; exits 2 when it is not running. Never loads a model: one that is not loaded has no template to show.

Usage: apollia-os chat template <SESSION_ID>

Arguments:​
  • <SESSION_ID> - Session id

apollia-os chat settings​

Read or replace what one conversation changes from its agent: its request settings, its instructions, the accesses it switches off

Usage: apollia-os chat settings <COMMAND>

Subcommands:​
  • get - Print what a conversation changes from its agent
  • set - Replace the settings of a conversation

apollia-os chat settings get​

Print what a conversation changes from its agent.

Reaches the runtime; exits 2 when it is not running.

Usage: apollia-os chat settings get <SESSION_ID>

Arguments:​
  • <SESSION_ID> - Session id

apollia-os chat settings set​

Replace the settings of a conversation.

Reaches the runtime; exits 2 when it is not running. The fields are preset, thinking, reasoning_effort (low, medium, high), preserve_thinking (the reasoning of the earlier answers goes back to the model), temperature, max_tokens, context_overflow (summarize_middle, sliding_window, stop_at_limit), instructions, disabled_accesses, proposed_accesses, only_accesses and profile_access. {} returns the conversation to the settings of its agent.

Usage: apollia-os chat settings set <SESSION_ID> <SETTINGS>

Arguments:​
  • <SESSION_ID> - Session id
  • <SETTINGS> - The settings, a JSON object. A field left out is inherited

apollia-os chat notes​

Read or replace the notes kept beside one conversation

Usage: apollia-os chat notes <COMMAND>

Subcommands:​
  • get - Print the notes kept beside a conversation
  • set - Replace the notes kept beside a conversation. They are never sent to a model

apollia-os chat notes get​

Print the notes kept beside a conversation.

Reaches the runtime; exits 2 when it is not running.

Usage: apollia-os chat notes get <SESSION_ID>

Arguments:​
  • <SESSION_ID> - Session id

apollia-os chat notes set​

Replace the notes kept beside a conversation. They are never sent to a model.

Reaches the runtime; exits 2 when it is not running.

Usage: apollia-os chat notes set <SESSION_ID> <NOTES>

Arguments:​
  • <SESSION_ID> - Session id
  • <NOTES> - The notes. An empty string erases them

apollia-os chat config​

Manage the Chat Libre configuration (system prompt, allowed tools, backend)

Usage: apollia-os chat config <COMMAND>

Subcommands:​
  • get - Print the settings of the free chat (the Apollia agent)
  • set - Update one setting of the free chat (the Apollia agent)
  • reset - Reset the settings to the defaults (no prompt, no tools, default model)
  • permissions - Manage persisted permission rules scoped to the Apollia Chat agent
  • authorizations - Inspect or revoke in-memory session authorizations

apollia-os chat config get​

Print the settings of the free chat (the Apollia agent)

Usage: apollia-os chat config get

apollia-os chat config set​

Update one setting of the free chat (the Apollia agent)

Usage: apollia-os chat config set <KEY> <VALUE>

Arguments:​
  • <KEY> - Field name: system-prompt, allowed-tools, or llm-backend
  • <VALUE> - New value. For allowed-tools, expects a comma-separated list. For llm-backend, the literal none clears the backend

apollia-os chat config reset​

Reset the settings to the defaults (no prompt, no tools, default model)

Usage: apollia-os chat config reset [OPTIONS]

Options:​
  • --confirm

apollia-os chat config permissions​

Manage persisted permission rules scoped to the Apollia Chat agent.

Mirrors the Desktop Settings → Chat permissions panel: lists or deletes rules stored in governance.db with agent_id = apollia:chat. The authorizations a running chat holds for its session only are not rules and are not visible here.

Usage: apollia-os chat config permissions <COMMAND>

Subcommands:​
  • list - List every persisted rule scoped to the Apollia Chat agent
  • delete - Delete a chat-scoped permission rule by id

apollia-os chat config permissions list​

List every persisted rule scoped to the Apollia Chat agent

Usage: apollia-os chat config permissions list [OPTIONS]

Options:​
  • --db <PATH> - Override the governance.db path (default: ~/.apollia/governance.db)

apollia-os chat config permissions delete​

Delete a chat-scoped permission rule by id

Usage: apollia-os chat config permissions delete [OPTIONS] <ID>

Arguments:​
  • <ID> - Rule id (as returned by chat-config permissions list)
Options:​
  • --confirm - Skip the confirmation prompt (required for scripts)
  • --db <PATH> - Override the governance.db path

apollia-os chat config authorizations​

Inspect or revoke in-memory session authorizations.

These authorizations live only in the running daemon's ChatSessionManager (never persisted to governance.db). The CLI cannot reach in-memory state from outside the daemon, so this subcommand prints an explanatory error and exits 1 unless / until a runtime route is added. Use the Desktop Settings → Permissions panel or restart the daemon to clear stale authorizations.

Usage: apollia-os chat config authorizations <COMMAND>

Subcommands:​
  • list - List active in-memory session authorizations (requires runtime route)
  • revoke - Revoke a single in-memory session authorization (requires runtime route)

apollia-os chat config authorizations list​

List active in-memory session authorizations (requires runtime route)

Usage: apollia-os chat config authorizations list

apollia-os chat config authorizations revoke​

Revoke a single in-memory session authorization (requires runtime route)

Usage: apollia-os chat config authorizations revoke [OPTIONS] <SESSION_ID> <TOOL>

Arguments:​
  • <SESSION_ID> - Session id
  • <TOOL> - Tool name
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os mcp​

MCP server management (list, add, remove, show, test, restart, update, raw-config, server)

Usage: apollia-os mcp <COMMAND>

Subcommands:​
  • list - List configured and, optionally, discovered MCP servers
  • add - Register a new MCP server with the runtime (persisted in the config)
  • remove - Remove an MCP server from the runtime
  • show - Show the details of an MCP server
  • test - Test the connection to an MCP server
  • restart - Restart an MCP server
  • update - Update the raw configuration of an existing MCP server
  • raw-config - Show the raw persisted configuration of an MCP server
  • oauth - Interactive OAuth (PKCE) management for HTTP/streamable-http MCP servers
  • secret - Manage MCP server secrets (env-var values) in the OS keychain
  • server - Serve the exposed agents and workflows to an MCP client over stdio

apollia-os mcp list​

List configured and, optionally, discovered MCP servers

Usage: apollia-os mcp list [OPTIONS]

Options:​

  • --discover - Scan the local network via mDNS and append discovered servers.

    Performs a 3-second broadcast scan for _apollia-mcp._tcp.local. in addition to listing servers from the configuration file.

  • --config <PATH> - Path to the MCP configuration file (default: ~/.apollia/mcp.toml)

  • --json - Output machine-readable JSON

apollia-os mcp add​

Register a new MCP server with the runtime (persisted in the config)

Usage: apollia-os mcp add [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Unique server name
Options:​

  • --command <COMMAND> - Executable to launch (stdio transport), without its arguments

  • --arg <ARG> - One argument passed to --command. Repeat it, in order, for each argument: --command npx --arg -y --arg @scope/server

  • --url <URL> - HTTP/SSE connection URL

  • --transport <TRANSPORT> - Transport. Defaults to streamable-http with --url, stdio otherwise

    Possible values: stdio, streamable-http, sse

apollia-os mcp remove​

Remove an MCP server from the runtime

Usage: apollia-os mcp remove [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Server name
Options:​
  • --confirm - Confirm without an interactive prompt

apollia-os mcp show​

Show the details of an MCP server

Usage: apollia-os mcp show <NAME>

Arguments:​
  • <NAME> - Server name

apollia-os mcp test​

Test the connection to an MCP server

Usage: apollia-os mcp test <TARGET>

Arguments:​
  • <TARGET> - URL or command to test

apollia-os mcp restart​

Restart an MCP server

Usage: apollia-os mcp restart <NAME>

Arguments:​
  • <NAME> - Server name

apollia-os mcp update​

Update the raw configuration of an existing MCP server.

At least one of --command, --arg or --url must be supplied. Fields that are omitted keep their previous value.

Usage: apollia-os mcp update [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Server name
Options:​
  • --command <COMMAND> - New stdio command (stdio transport)
  • --arg <ARG> - New argument list for the command, one --arg per argument. Given once or more, it replaces the stored list whole
  • --url <URL> - New HTTP/SSE URL

apollia-os mcp raw-config​

Show the raw persisted configuration of an MCP server.

Reads mcp.db directly via the runtime and returns the original definition (useful for bisecting a configuration regression).

Usage: apollia-os mcp raw-config <NAME>

Arguments:​
  • <NAME> - Server name

apollia-os mcp oauth​

Interactive OAuth (PKCE) management for HTTP/streamable-http MCP servers.

Same keychain entries as the Desktop wizard (apollia-mcp-oauth/<server>), so once a server is connected from one surface the other inherits the token.

Usage: apollia-os mcp oauth <COMMAND>

Subcommands:​
  • login - Run the interactive PKCE login flow for <server> and persist the token
  • status - Report the persisted-token status for one or every configured server
  • logout - Delete the persisted token for <server> from the OS keychain
  • client-id - Manage per-env-var OAuth client-id overrides stored in the OS keychain
  • discover - Run RFC 9728 + RFC 8414 OAuth discovery against <server> and print the resulting authorization server, scopes and endpoints

apollia-os mcp oauth login​

Run the interactive PKCE login flow for <server> and persist the token.

Opens the OAuth authorisation URL in the system browser, prints it on stdout (so headless setups can copy / paste it), waits for the authorisation server to redirect back to the loopback listener, then stores the resulting access + refresh tokens in the OS keychain under apollia-mcp-oauth/<server>.

Usage: apollia-os mcp oauth login [OPTIONS] <SERVER>

Arguments:​
  • <SERVER> - Server name as declared in mcp.db (matches the Desktop wizard)
Options:​
  • --scopes <SCOPE> - Optional comma-separated scope list. Omit to defer to the AS's scopes_supported (recommended)
  • --client-id <ID> - Override the OAuth client id resolution (for tenants running their own AS app, usually unnecessary)
  • --db <PATH> - Override the path to mcp.db (default: ~/.apollia/mcp.db)

apollia-os mcp oauth status​

Report the persisted-token status for one or every configured server.

Surfaces token expiry, granted scopes, and identity claims (sub, email) without revealing the access token itself.

Usage: apollia-os mcp oauth status [OPTIONS] [SERVER]

Arguments:​
  • <SERVER> - Optional server name. When omitted, lists every server with a stored token plus those declared in mcp.db but unauthenticated
Options:​
  • --db <PATH>

apollia-os mcp oauth logout​

Delete the persisted token for <server> from the OS keychain.

The authorisation server is not notified: call the provider's revocation endpoint manually if a server-side revocation is required.

Usage: apollia-os mcp oauth logout [OPTIONS] <SERVER>

Arguments:​
  • <SERVER> - Server name to forget
Options:​
  • --confirm - Skip the confirmation prompt

apollia-os mcp oauth client-id​

Manage per-env-var OAuth client-id overrides stored in the OS keychain.

Mirrors the Desktop Settings → MCP → "OAuth client id" panel. Resolution chain: env var > keychain (this command) > build-time default.

Usage: apollia-os mcp oauth client-id <COMMAND>

Subcommands:​
  • set - Persist <value> as the OAuth client id for the env var <env_var>
  • clear - Remove the persisted client id stored under <env_var>

apollia-os mcp oauth client-id set​

Persist <value> as the OAuth client id for the env var <env_var>.

The env var is the same one the connector wizard surfaces (e.g. APOLLIA_FIGMA_CLIENT_ID). Pass an empty value to fail validation; use clear to remove.

Usage: apollia-os mcp oauth client-id set <ENV_VAR> <VALUE>

Arguments:​
  • <ENV_VAR> - Env var name (e.g. APOLLIA_FIGMA_CLIENT_ID)
  • <VALUE> - New client id value

apollia-os mcp oauth client-id clear​

Remove the persisted client id stored under <env_var>

Usage: apollia-os mcp oauth client-id clear [OPTIONS] <ENV_VAR>

Arguments:​
  • <ENV_VAR> - Env var name
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os mcp oauth discover​

Run RFC 9728 + RFC 8414 OAuth discovery against <server> and print the resulting authorization server, scopes and endpoints.

Read-only: no token is exchanged and no secret is written. Useful to confirm an HTTP MCP server's PRM + AS metadata before invoking login.

Usage: apollia-os mcp oauth discover [OPTIONS] <SERVER>

Arguments:​
  • <SERVER> - Server name as declared in mcp.db
Options:​
  • --db <PATH> - Override the path to mcp.db (default: ~/.apollia/mcp.db)

apollia-os mcp secret​

Manage MCP server secrets (env-var values) in the OS keychain.

Mirrors the Desktop secret store: entries are keyed by {server}:{env_var} under the keychain service apollia-mcp, so a secret stored by the CLI is read transparently by the Desktop runtime.

Usage: apollia-os mcp secret <COMMAND>

Subcommands:​
  • set - Persist <value> as the secret for (<server>, <env_var>)
  • delete - Delete the stored secret for (<server>, <env_var>)

apollia-os mcp secret set​

Persist <value> as the secret for (<server>, <env_var>).

The value is written to the OS keychain under service apollia-mcp and composite key {server}:{env_var}. Use delete to remove. The CLI does not echo the value back, but it is stored as-is (no trimming beyond stripping leading / trailing whitespace).

Usage: apollia-os mcp secret set <SERVER> <ENV_VAR> <VALUE>

Arguments:​
  • <SERVER> - MCP server name (matches the name in mcp.db / mcp.toml)
  • <ENV_VAR> - Environment variable name (e.g. NOTION_API_KEY)
  • <VALUE> - Secret value to store

apollia-os mcp secret delete​

Delete the stored secret for (<server>, <env_var>)

Usage: apollia-os mcp secret delete [OPTIONS] <SERVER> <ENV_VAR>

Arguments:​
  • <SERVER> - MCP server name
  • <ENV_VAR> - Environment variable name
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os mcp server​

Serve the exposed agents and workflows to an MCP client over stdio.

A bridge to the running daemon: an MCP client (an editor, another assistant) spawns it and sees the agents and workflows marked exposed, and nothing else. The daemon refuses it until mcp.server_enabled is turned on.

Usage: apollia-os mcp server

apollia-os update​

Check for and install updates from GitHub Releases

Usage: apollia-os update [OPTIONS]

Options:​
  • --check - Only check for a newer version without downloading or installing
  • --yes - Install without asking for interactive confirmation

apollia-os package​

Agent package archives: build, inspect, preview and install a .apo, and trust publisher keys

Usage: apollia-os package <COMMAND>

Subcommands:​
  • new - Write the starting folder of a package: an agent declared in apollia.toml and one Python tool
  • build - Build a .apo archive from a package folder
  • inspect - Show the manifest, the entries and the signature state of a .apo archive
  • preview - Show what a .apo package contains and asks for, before installing it
  • install - Install a .apo package, or update it
  • trust - Trusted publisher keys: a package signed by one is shown under its label

apollia-os package new​

Write the starting folder of a package: an agent declared in apollia.toml and one Python tool.

The folder is <name> under the current folder, or under --output-dir. It builds as written with package build. Nothing is overwritten: an existing folder is refused.

Usage: apollia-os package new [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Package name: lowercase letters, digits, - and _
Options:​
  • --output-dir <DIR> - Folder to create the package folder in. Default: the current one

apollia-os package build​

Build a .apo archive from a package folder.

Validates apollia.toml, refuses a folder whose Python modules define tools or workflows that the manifest does not describe (write the descriptors with python -m apollia describe <folder>), and writes the archive. No Python code runs.

Usage: apollia-os package build [OPTIONS] <DIR>

Arguments:​
  • <DIR> - Package folder, holding apollia.toml at its root
Options:​

  • --sign - Sign the archive with the author key. The key is read from the secret store under --key; it is generated and stored there the first time

  • --key <LABEL> - Label of the author key in the secret store

    Default value: default

  • -o, --output <FILE> - Archive to write. Default: <name>-<version>.apo in the current folder

apollia-os package inspect​

Show the manifest, the entries and the signature state of a .apo archive.

The signature state is unsigned, or signed with the declared publisher and the fingerprint of the key. A signature that does not match the content is refused with exit 1.

Usage: apollia-os package inspect <FILE>

Arguments:​
  • <FILE> - The .apo archive

apollia-os package preview​

Show what a .apo package contains and asks for, before installing it.

Reports the agents, workflows and tools, the accesses each agent asks for and what each permits, the publisher and the signature (trusted when its key is in the keyring), the connections the package requires (present or missing) and the MCP servers it brings, and, for an installed package, what the new version adds. Nothing is written. Needs the runtime.

Usage: apollia-os package preview <FILE>

Arguments:​
  • <FILE> - The .apo archive

apollia-os package install​

Install a .apo package, or update it.

A signature that does not hold is refused; an unsigned package installs with a notice. The local overrides of its agents are kept on update. Needs the runtime.

Usage: apollia-os package install [OPTIONS] <FILE>

Arguments:​
  • <FILE> - The .apo archive
Options:​
  • --confirm-deps - Accept the Python dependencies the package installs
  • --confirm-changes - Accept what an update adds: accesses, required connections, MCP servers (read package preview first)
  • --allow-downgrade - Install a version older than the installed one

apollia-os package trust​

Trusted publisher keys: a package signed by one is shown under its label

Usage: apollia-os package trust <COMMAND>

Subcommands:​
  • import - Trust a publisher's public key, given as 64 hexadecimal characters or as a file holding them
  • list - List the trusted publisher keys
  • remove - Stop trusting a publisher key

apollia-os package trust import​

Trust a publisher's public key, given as 64 hexadecimal characters or as a file holding them

Usage: apollia-os package trust import --label <LABEL> <KEY>

Arguments:​
  • <KEY> - The key, or a file holding it
Options:​
  • --label <LABEL> - Name to show for the publisher

apollia-os package trust list​

List the trusted publisher keys

Usage: apollia-os package trust list

apollia-os package trust remove​

Stop trusting a publisher key

Usage: apollia-os package trust remove [OPTIONS] <FINGERPRINT>

Arguments:​
  • <FINGERPRINT> - SHA-256 fingerprint of the key, as package trust list shows it
Options:​
  • --confirm - Remove without asking

apollia-os policy​

Organisation policy: create the key, write, sign, verify, show

Usage: apollia-os policy <COMMAND>

Subcommands:​
  • keygen - Create the organisation key pair in a folder
  • init - Write a commented policy.toml that imposes nothing, dated now
  • sign - Sign the policy.toml of a folder with the organisation private key
  • verify - Check a policy folder: schema, signature, and rights in the system folder
  • show - Show the policy the runtime reads at startup, or none

apollia-os policy keygen​

Create the organisation key pair in a folder.

Writes org.key, the private key, readable by its owner only from the moment it is created, and org.pub, the public key; prints the fingerprint of the public key. Existing files are never replaced. Keep org.key off the workstations.

Usage: apollia-os policy keygen --out <DIR>

Options:​
  • --out <DIR> - Folder that receives org.key and org.pub, created when missing

apollia-os policy init​

Write a commented policy.toml that imposes nothing, dated now.

The folder is created when missing; an existing policy.toml is never replaced.

Usage: apollia-os policy init <DIR>

Arguments:​
  • <DIR> - Policy folder

apollia-os policy sign​

Sign the policy.toml of a folder with the organisation private key.

Writes SIGNATURE and org.pub next to it, replacing earlier ones. A policy that breaks the schema is not signed.

Usage: apollia-os policy sign [OPTIONS] --key <FILE> <DIR>

Arguments:​
  • <DIR> - Policy folder
Options:​

  • --key <FILE> - The organisation private key, as written by policy keygen

  • --publisher <NAME> - Publisher name declared in the signature

    Default value: Organisation

apollia-os policy verify​

Check a policy folder: schema, signature, and rights in the system folder.

The rights are checked when the folder is the one the runtime reads. A folder that does not hold is refused with exit 1, whatever the cause; the cause (schema, signature, key, owner, or missing when the folder does not exist) is named in the message, and --json carries the verdict, the reason and its detail.

Usage: apollia-os policy verify <DIR>

Arguments:​
  • <DIR> - Policy folder

apollia-os policy show​

Show the policy the runtime reads at startup, or none

Usage: apollia-os policy show

apollia-os workspace​

Workspace inspection and initialization (status, init)

Usage: apollia-os workspace <COMMAND>

Subcommands:​
  • status - Show the status of the current workspace
  • init - Initialise APOLLIA.md in the current directory

apollia-os workspace status​

Show the status of the current workspace

Usage: apollia-os workspace status

apollia-os workspace init​

Initialise APOLLIA.md in the current directory

Usage: apollia-os workspace init [OPTIONS]

Options:​

  • --force - Overwrite APOLLIA.md if it already exists

    Default value: false

apollia-os review​

Automated code or plan review via the apollia-review agent

Usage: apollia-os review [OPTIONS]

Options:​
  • --task <ID> - Apollia task ID whose execution plan should be reviewed
  • --pr <N> - GitHub pull-request number to fetch via gh pr diff
  • --diff <FILE> - Local diff / patch file to analyse

apollia-os approvals​

The decisions waiting for you (pending)

Usage: apollia-os approvals <COMMAND>

Subcommands:​
  • pending - List every decision waiting for you: consents, paused tasks, batch items waiting for an access, questions from agents and from workflows
  • decide - Answer one waiting decision: the run that waits goes on with it

apollia-os approvals pending​

List every decision waiting for you: consents, paused tasks, batch items waiting for an access, questions from agents and from workflows

Usage: apollia-os approvals pending

apollia-os approvals decide​

Answer one waiting decision: the run that waits goes on with it

Usage: apollia-os approvals decide [OPTIONS] <ID> <ANSWER>

Arguments:​

  • <ID> - The id of the item, as approvals pending prints it

  • <ANSWER> - The answer, one of those the item takes

    Possible values:

    • once: This call, or this item, only
    • always: This one and every later one of the same agent in the same family
    • refuse: Not this one
    • answer: The answer to a question, given with --value
Options:​
  • --value <TEXT> - The answer to a question: one of its choices, or free text
  • --reason <TEXT> - Why, for a refusal; handed to the run that asked

apollia-os batch​

Run an agent on every item of a source (run, status, list, accesses, pause, resume, stop, retry, export)

Usage: apollia-os batch <COMMAND>

Subcommands:​
  • run - Run an agent on every item of a source, in the runtime
  • status - Show a batch: its state, its counters and each of its items
  • list - List the batches, newest first
  • accesses - List the sensitive accesses of an agent, those run --grant may grant
  • pause - Pause a running batch: no further item starts
  • resume - Resume a paused batch
  • stop - Stop a batch: running items are cancelled, pending ones never run
  • retry - Run the failed items of a batch, and those waiting for an access, again
  • export - Export the result of a batch to a file: one row per item, its input columns, its output, its status and the sources it cites

apollia-os batch run​

Run an agent on every item of a source, in the runtime

Usage: apollia-os batch run [OPTIONS] --source-type <SOURCE_TYPE> --source <SOURCE> <AGENT>

Arguments:​
  • <AGENT> - The agent every item is run by: a stored agent without code
Options:​
  • --source-type <SOURCE_TYPE> - The type of source, as a reader registers it
  • --source <SOURCE> - What the source is opened on: a file, a folder, a connection
  • --option <KEY=VALUE> - An option of the source type, as key=value; repeatable
  • --grant <GRANTS> - A sensitive access granted for the duration of the batch, as batch accesses lists it; repeatable
  • --concurrency <CONCURRENCY> - How many items run at once, 1 to 16 (default 1)
  • --max-failures <MAX_FAILURES> - Failed items tolerated before the batch is interrupted (default 10)

apollia-os batch status​

Show a batch: its state, its counters and each of its items

Usage: apollia-os batch status <BATCH_ID>

Arguments:​
  • <BATCH_ID> - The batch id batch run printed

apollia-os batch list​

List the batches, newest first

Usage: apollia-os batch list [OPTIONS]

Options:​

  • --limit <LIMIT> - At most this many batches

    Default value: 50

apollia-os batch accesses​

List the sensitive accesses of an agent, those run --grant may grant

Usage: apollia-os batch accesses <AGENT>

Arguments:​
  • <AGENT> - The agent a batch would run

apollia-os batch pause​

Pause a running batch: no further item starts

Usage: apollia-os batch pause <BATCH_ID>

Arguments:​
  • <BATCH_ID> - The batch id

apollia-os batch resume​

Resume a paused batch

Usage: apollia-os batch resume <BATCH_ID>

Arguments:​
  • <BATCH_ID> - The batch id

apollia-os batch stop​

Stop a batch: running items are cancelled, pending ones never run

Usage: apollia-os batch stop <BATCH_ID>

Arguments:​
  • <BATCH_ID> - The batch id

apollia-os batch retry​

Run the failed items of a batch, and those waiting for an access, again

Usage: apollia-os batch retry [OPTIONS] <BATCH_ID>

Arguments:​
  • <BATCH_ID> - The batch id
Options:​
  • --grant <GRANTS> - A sensitive access granted for the rest of the batch; repeatable

apollia-os batch export​

Export the result of a batch to a file: one row per item, its input columns, its output, its status and the sources it cites

Usage: apollia-os batch export [OPTIONS] --format <FORMAT> <BATCH_ID>

Arguments:​
  • <BATCH_ID> - The batch id
Options:​

  • --format <FORMAT> - The file format

    Possible values: xlsx, csv, json

  • -o, --output <PATH> - Where to write the file; - writes it to standard output. Default: batch-<id>.<format> in the current folder

apollia-os workflow​

Run the workflows of installed packages (show, run, status, logs, cancel)

Usage: apollia-os workflow <COMMAND>

Subcommands:​
  • show - Show a workflow: what it does, its steps, and each input with its type
  • run - Run a workflow, in the runtime
  • status - Show a run: its status, its result and each of its steps
  • logs - The runs of a workflow, newest first
  • cancel - Stop a run: its step in progress is interrupted, the next ones never start

apollia-os workflow show​

Show a workflow: what it does, its steps, and each input with its type

Usage: apollia-os workflow show <WORKFLOW>

Arguments:​
  • <WORKFLOW> - The workflow, <package>/<workflow>

apollia-os workflow run​

Run a workflow, in the runtime

Usage: apollia-os workflow run [OPTIONS] <WORKFLOW>

Arguments:​
  • <WORKFLOW> - The workflow, <package>/<workflow>
Options:​
  • --input <KEY=VALUE> - An input, as key=value; repeatable. A value is read as the type the workflow declares for it: a date as YYYY-MM-DD, a file as its absolute path
  • --wait - Follow the run to its end; exit 3 when it fails or is stopped

apollia-os workflow status​

Show a run: its status, its result and each of its steps

Usage: apollia-os workflow status <RUN_ID>

Arguments:​
  • <RUN_ID> - The run id workflow run printed

apollia-os workflow logs​

The runs of a workflow, newest first

Usage: apollia-os workflow logs [OPTIONS] <WORKFLOW>

Arguments:​
  • <WORKFLOW> - The workflow, <package>/<workflow>
Options:​

  • --limit <LIMIT> - At most this many runs

    Default value: 50

apollia-os workflow cancel​

Stop a run: its step in progress is interrupted, the next ones never start

Usage: apollia-os workflow cancel [OPTIONS] <RUN_ID>

Arguments:​
  • <RUN_ID> - The run id
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os resilience​

Circuit breaker inspection and reset (list, show, reset)

Usage: apollia-os resilience <COMMAND>

Subcommands:​
  • list - List all registered circuit breakers with their state and counters
  • show - Show the state of a single circuit breaker
  • reset - Reset a circuit breaker to CLOSED state immediately

apollia-os resilience list​

List all registered circuit breakers with their state and counters

Usage: apollia-os resilience list

apollia-os resilience show​

Show the state of a single circuit breaker

Usage: apollia-os resilience show <TOOL_NAME>

Arguments:​
  • <TOOL_NAME> - Tool name as registered in the Tool Registry

apollia-os resilience reset​

Reset a circuit breaker to CLOSED state immediately

Usage: apollia-os resilience reset [OPTIONS] <TOOL_NAME>

Arguments:​
  • <TOOL_NAME> - Tool name to reset
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os plan​

Plan domain management (cache: stats, clear, evict)

Usage: apollia-os plan <COMMAND>

Subcommands:​
  • cache - Plan cache management (stats, clear, evict)

apollia-os plan cache​

Plan cache management (stats, clear, evict)

Usage: apollia-os plan cache <COMMAND>

Subcommands:​
  • stats - Display cache statistics (total entries, hits, oldest/newest entry)
  • clear - Remove all cached plans
  • evict - Evict entries older than --max-age-days days (default: 7)

apollia-os plan cache stats​

Display cache statistics (total entries, hits, oldest/newest entry)

Usage: apollia-os plan cache stats

apollia-os plan cache clear​

Remove all cached plans.

Prompts for confirmation unless --confirm is passed.

Usage: apollia-os plan cache clear [OPTIONS]

Options:​
  • --confirm - Skip the interactive confirmation prompt. --force is the name this flag published before the rule of section 2 and stays accepted

apollia-os plan cache evict​

Evict entries older than --max-age-days days (default: 7)

Usage: apollia-os plan cache evict [OPTIONS]

Options:​

  • --max-age-days <DAYS> - Maximum entry age in days before eviction

    Default value: 7

  • --confirm - Skip the interactive confirmation prompt

apollia-os service​

Run the runtime as a service of your session (install, uninstall, status)

Usage: apollia-os service <COMMAND>

Subcommands:​
  • install - Install the runtime as a service of your session and start it
  • uninstall - Stop the service and remove its definition
  • status - Report whether the service is installed and running

apollia-os service install​

Install the runtime as a service of your session and start it.

macOS: a LaunchAgent; Linux: a systemd user unit; Windows: a task at logon. No administrator right is needed.

Usage: apollia-os service install [OPTIONS]

Options:​
  • --no-load - Write the service definition without handing it to the service manager: nothing starts now, the next logon starts it

apollia-os service uninstall​

Stop the service and remove its definition.

Prompts for confirmation unless --confirm is passed.

Usage: apollia-os service uninstall [OPTIONS]

Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os service status​

Report whether the service is installed and running

Usage: apollia-os service status

apollia-os doctor​

Diagnose the local Apollia environment (no runtime required).

Verifies the Apollia home directory, the config file, local SQLite databases, the Python bridge, and the runtime socket. Prints a status table and exits 0 when healthy, 1 when at least one check errors.

Usage: apollia-os doctor

apollia-os logs​

Tail or follow the runtime log file.

Defaults to ~/.apollia/logs/runtime.log. When this file is absent the command prints a hint explaining how to redirect daemon stderr.

Usage: apollia-os logs [OPTIONS]

Options:​

  • --file <PATH> - Path to the log file (default: ~/.apollia/logs/runtime.log)

  • --last <N> - Print only the last N lines (default: 50)

    Default value: 50

  • -f, --follow - Follow the file and stream new lines as they are appended

apollia-os version​

Print the binary version (use --json for machine-readable output)

Usage: apollia-os version

apollia-os connector​

Native SaaS connector management (list, accounts, test, revoke).

Operates on the multi-account keyring without requiring the runtime to be started. Accounts are connected from the desktop app (Settings > Integrations); the OAuth flow needs a browser redirect, so there is no CLI equivalent.

Usage: apollia-os connector <COMMAND>

Subcommands:​
  • list - List all native SaaS connectors registered in this build
  • accounts - List OAuth-connected accounts for one or all providers
  • test - Probe the connector for an account by calling the userinfo endpoint
  • revoke - Revoke the stored token for (provider, account)
  • client-id - Manage OAuth client_id overrides in ~/.apollia/oauth-clients.toml
  • client-secret - Manage OAuth client_secret overrides in ~/.apollia/oauth-clients.toml
  • api-key - Manage API key overrides (Google Picker) in ~/.apollia/oauth-clients.toml
  • imap - A mailbox reached over IMAP with an application password: test, add, list. Read-only: nothing in the mailbox is ever changed
  • drive - Manage per-account Google Drive folder preferences

apollia-os connector list​

List all native SaaS connectors registered in this build.

Output covers the connector id, display name, publisher, and the services it exposes (e.g. gmail, gcal, gdrive).

Usage: apollia-os connector list

apollia-os connector accounts​

List OAuth-connected accounts for one or all providers

Usage: apollia-os connector accounts [OPTIONS]

Options:​
  • --provider <PROVIDER> - Filter by provider: google or microsoft. Omit to list both

apollia-os connector test​

Probe the connector for an account by calling the userinfo endpoint.

Returns the live identity claim and the scopes the upstream Authorization Server reports as granted, the same shape used by connector.check() inside the runtime.

Usage: apollia-os connector test <PROVIDER> <ACCOUNT>

Arguments:​
  • <PROVIDER> - Provider id: google or microsoft
  • <ACCOUNT> - Account identifier (email when supplied during OAuth login)

apollia-os connector revoke​

Revoke the stored token for (provider, account).

Only the local keyring entry is cleared, the upstream Authorization Server is not notified. Use the provider's web revocation page for a server-side revocation.

Usage: apollia-os connector revoke [OPTIONS] <PROVIDER> <ACCOUNT>

Arguments:​
  • <PROVIDER> - Provider id
  • <ACCOUNT> - Account id to revoke
Options:​
  • --confirm - Skip the confirmation prompt (required for scripts)

apollia-os connector client-id​

Manage OAuth client_id overrides in ~/.apollia/oauth-clients.toml.

Power-user / Expert Mode: lets a CLI operator plug in their own Google or Microsoft client_id without rebuilding the binary. Resolution chain per provider is env var > oauth-clients.toml > compiled default.

Usage: apollia-os connector client-id <COMMAND>

Subcommands:​
  • list - List every provider's effective client_id + source + override
  • set - Set the client_id override for <provider>

apollia-os connector client-id list​

List every provider's effective client_id + source + override

Usage: apollia-os connector client-id list

apollia-os connector client-id set​

Set the client_id override for <provider>.

Pass an empty string ("") to clear the override.

Usage: apollia-os connector client-id set <PROVIDER> <CLIENT_ID>

Arguments:​
  • <PROVIDER> - Provider id: google or microsoft
  • <CLIENT_ID> - New client_id value. Empty string clears the override

apollia-os connector client-secret​

Manage OAuth client_secret overrides in ~/.apollia/oauth-clients.toml.

Required by Google (Installed App needs a secret) and a no-op for Microsoft (public client per spec). File is created on demand with 0o600 permissions on Unix.

Usage: apollia-os connector client-secret <COMMAND>

Subcommands:​
  • set - Set the client_secret override for <provider>

apollia-os connector client-secret set​

Set the client_secret override for <provider>.

Pass an empty string ("") to clear the override. The CLI does not echo the secret back, but it is written to ~/.apollia/oauth-clients.toml.

Usage: apollia-os connector client-secret set <PROVIDER> <CLIENT_SECRET>

Arguments:​
  • <PROVIDER> - Provider id: google or microsoft
  • <CLIENT_SECRET> - New client_secret value. Empty string clears the override

apollia-os connector api-key​

Manage API key overrides (Google Picker) in ~/.apollia/oauth-clients.toml.

Google-only today. Microsoft slot is reserved for the OneDrive File Picker if added later.

Usage: apollia-os connector api-key <COMMAND>

Subcommands:​
  • set - Set the API key override for <provider>

apollia-os connector api-key set​

Set the API key override for <provider>.

Pass an empty string ("") to clear the override.

Usage: apollia-os connector api-key set <PROVIDER> <API_KEY>

Arguments:​
  • <PROVIDER> - Provider id: google or microsoft
  • <API_KEY> - New API key value. Empty string clears the override

apollia-os connector imap​

A mailbox reached over IMAP with an application password: test, add, list. Read-only: nothing in the mailbox is ever changed

Usage: apollia-os connector imap <COMMAND>

Subcommands:​
  • test - Log in to a mailbox and open its inbox read-only; store nothing
  • add - Verify a mailbox like test, then connect it: the password goes to the secret store, the rest to ~/.apollia/imap-accounts.json
  • list - List the mailboxes connected on this machine

apollia-os connector imap test​

Log in to a mailbox and open its inbox read-only; store nothing.

For a known provider (Gmail, iCloud, Yahoo, Orange, Free, La Poste) the address is enough; the server and port are filled in.

Usage: apollia-os connector imap test [OPTIONS] <EMAIL>

Arguments:​
  • <EMAIL> - Address of the mailbox
Options:​
  • --host <HOST> - IMAP server; filled from the address for a known provider
  • --port <PORT> - IMAP port, implicit TLS; the provider's, else 993
  • --username <USERNAME> - Identifier sent at login; the address when absent
  • --password-stdin - Read the application password from the first line of standard input, instead of APOLLIA_IMAP_PASSWORD

apollia-os connector imap add​

Verify a mailbox like test, then connect it: the password goes to the secret store, the rest to ~/.apollia/imap-accounts.json

Usage: apollia-os connector imap add [OPTIONS] <EMAIL>

Arguments:​
  • <EMAIL> - Address of the mailbox
Options:​
  • --host <HOST> - IMAP server; filled from the address for a known provider
  • --port <PORT> - IMAP port, implicit TLS; the provider's, else 993
  • --username <USERNAME> - Identifier sent at login; the address when absent
  • --password-stdin - Read the application password from the first line of standard input, instead of APOLLIA_IMAP_PASSWORD

apollia-os connector imap list​

List the mailboxes connected on this machine

Usage: apollia-os connector imap list

apollia-os connector drive​

Manage per-account Google Drive folder preferences.

Operates on ~/.apollia/drive-prefs.toml and is independent of the runtime. The picked sub-group lists folders captured via the Desktop Picker (the CLI cannot pick, no UI, but can review and remove them).

Usage: apollia-os connector drive <COMMAND>

Subcommands:​
  • folder - Manage the per-account Drive root folder path

apollia-os connector drive folder​

Manage the per-account Drive root folder path

Usage: apollia-os connector drive folder <COMMAND>

Subcommands:​
  • list - List the folder override + effective path for every Google account
  • set - Set the folder path override for <account>
  • reset - Reset the folder override for <account> (falls back to the default)
  • picked - Manage the picked-folder list captured via the Desktop Drive Picker

apollia-os connector drive folder list​

List the folder override + effective path for every Google account

Usage: apollia-os connector drive folder list

apollia-os connector drive folder set​

Set the folder path override for <account>

Usage: apollia-os connector drive folder set <ACCOUNT> <PATH>

Arguments:​
  • <ACCOUNT> - Account id (typically the Google email)
  • <PATH> - New folder path (e.g. Apollia/Workspace)

apollia-os connector drive folder reset​

Reset the folder override for <account> (falls back to the default)

Usage: apollia-os connector drive folder reset [OPTIONS] <ACCOUNT>

Arguments:​
  • <ACCOUNT> - Account id
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os connector drive folder picked​

Manage the picked-folder list captured via the Desktop Drive Picker

Usage: apollia-os connector drive folder picked <COMMAND>

Subcommands:​
  • list - List the picked Drive folders persisted for <account>
  • remove - Remove a picked folder from the persisted list

apollia-os connector drive folder picked list​

List the picked Drive folders persisted for <account>

Usage: apollia-os connector drive folder picked list <ACCOUNT>

Arguments:​
  • <ACCOUNT> - Account id

apollia-os connector drive folder picked remove​

Remove a picked folder from the persisted list

Usage: apollia-os connector drive folder picked remove [OPTIONS] <ACCOUNT> <FOLDER_ID>

Arguments:​
  • <ACCOUNT> - Account id
  • <FOLDER_ID> - Drive folder id (the same id surfaced by picked list)
Options:​
  • --confirm - Skip the interactive confirmation prompt

apollia-os config​

Global apollia.toml management (get, set, validate, edit, show).

Edits the on-disk config without touching the runtime. The section helpers tools config and stt config remain available for their respective slices.

Usage: apollia-os config <COMMAND>

Subcommands:​
  • get - Print the on-disk apollia.toml (or a single value at KEY_PATH)
  • set - Write VALUE at KEY_PATH, preserving formatting and comments
  • validate - Parse the config file and report any error
  • edit - Open the config file in $EDITOR
  • show - Print the resolved configuration (parsed struct as JSON)
  • keys - List every key of apollia.toml: path, type, default, reload class, whether the organization policy can fix it, and whether it is withdrawn
  • reset - Wipe ~/.apollia/, an irreversible factory reset

apollia-os config get​

Print the on-disk apollia.toml (or a single value at KEY_PATH).

KEY_PATH follows dotted notation, e.g. llm.default or runtime.bind_addr.

Usage: apollia-os config get [OPTIONS] [KEY]

Arguments:​
  • <KEY> - Optional dotted key path
Options:​
  • --file <PATH> - Optional config file path override

apollia-os config set​

Write VALUE at KEY_PATH, preserving formatting and comments.

VALUE is parsed as a TOML scalar: bare booleans, integers, and floats are recognized; everything else is treated as a string. Use a quoted argument when the value contains spaces or special characters.

Usage: apollia-os config set [OPTIONS] <KEY> <VALUE>

Arguments:​
  • <KEY> - Dotted key path
  • <VALUE> - Value to write
Options:​
  • --file <PATH> - Optional config file path override

apollia-os config validate​

Parse the config file and report any error.

Exits 0 when the file is absent or valid, 1 otherwise.

Usage: apollia-os config validate [OPTIONS]

Options:​
  • --file <PATH> - Optional config file path override

apollia-os config edit​

Open the config file in $EDITOR.

Refuses to run when stdout is not a TTY or --json is set.

Usage: apollia-os config edit [OPTIONS]

Options:​
  • --file <PATH> - Optional config file path override

apollia-os config show​

Print the resolved configuration (parsed struct as JSON).

Cascades through file > defaults. Environment overlay is performed at runtime startup and is not reproduced here.

Usage: apollia-os config show [OPTIONS]

Options:​
  • --file <PATH> - Optional config file path override

apollia-os config keys​

List every key of apollia.toml: path, type, default, reload class, whether the organization policy can fix it, and whether it is withdrawn

Usage: apollia-os config keys

apollia-os config reset​

Wipe ~/.apollia/, an irreversible factory reset.

Deletes every SQLite database, log, journal, memory file, OAuth client override, and apollia.toml stored under ~/.apollia/. Keychain entries (OS-managed) are NOT touched: use connector revoke or mcp oauth logout to clear those.

Usage: apollia-os config reset [OPTIONS]

Options:​
  • --confirm - Skip the interactive confirmation prompt (required for scripts)
  • --dry-run - Print the resolved Apollia home and the entries that would be removed, but do not delete anything
  • --home <PATH> - Override the Apollia home path (default: ~/.apollia)

apollia-os profile​

User profile management (show, set, forget, reset, export, import).

Operates on ~/.apollia/user_memory.db directly; no runtime required.

Usage: apollia-os profile <COMMAND>

Subcommands:​
  • list - List the profiles: identifier, name, and which one is the default
  • show - Display a profile: its fields, then the free-form entries every profile shares. Without an identifier, the default profile
  • create - Create a profile with empty fields; it is not the default
  • rename - Rename a profile
  • set - Write one field of a profile: name, role, function, tools, preferences or free_text. Any other key is a free-form entry, shared by every profile
  • set-default - Make a profile the default; the previous default stops being one
  • delete - Delete a profile. The default profile cannot be deleted: make another one the default first
  • forget - Remove the entry stored at KEY
  • reset - Reset the entire profile (deletes every entry)
  • schema - Print the canonical schema (the known structured fields)
  • export - Dump every entry as a JSON array on stdout (or to --output)
  • import - Import entries from a JSON file produced by export

apollia-os profile list​

List the profiles: identifier, name, and which one is the default

Usage: apollia-os profile list [OPTIONS]

Options:​
  • --db <PATH> - Optional override for the user_memory.db path

apollia-os profile show​

Display a profile: its fields, then the free-form entries every profile shares. Without an identifier, the default profile

Usage: apollia-os profile show [OPTIONS] [ID]

Arguments:​
  • <ID> - Profile identifier, or default (the default when omitted)
Options:​
  • --db <PATH> - Optional override for the user_memory.db path

apollia-os profile create​

Create a profile with empty fields; it is not the default

Usage: apollia-os profile create [OPTIONS] <NAME>

Arguments:​
  • <NAME> - Display name of the profile (e.g. Formateur)
Options:​
  • --db <PATH>

apollia-os profile rename​

Rename a profile

Usage: apollia-os profile rename [OPTIONS] <ID> <NAME>

Arguments:​
  • <ID> - Profile identifier, or default
  • <NAME> - New display name
Options:​
  • --db <PATH>

apollia-os profile set​

Write one field of a profile: name, role, function, tools, preferences or free_text. Any other key is a free-form entry, shared by every profile

Usage: apollia-os profile set [OPTIONS] <ID> <FIELD> <VALUE>

Arguments:​
  • <ID> - Profile identifier, or default
  • <FIELD> - Field to write (e.g. role)
  • <VALUE> - Value to store; an empty value empties a field
Options:​
  • --db <PATH>

apollia-os profile set-default​

Make a profile the default; the previous default stops being one

Usage: apollia-os profile set-default [OPTIONS] <ID>

Arguments:​
  • <ID> - Profile identifier
Options:​
  • --db <PATH>

apollia-os profile delete​

Delete a profile. The default profile cannot be deleted: make another one the default first

Usage: apollia-os profile delete [OPTIONS] <ID>

Arguments:​
  • <ID> - Profile identifier
Options:​
  • --confirm - Skip the interactive confirmation prompt
  • --db <PATH>

apollia-os profile forget​

Remove the entry stored at KEY

Usage: apollia-os profile forget [OPTIONS] <KEY>

Arguments:​
  • <KEY> - Profile key to remove
Options:​
  • --confirm - Skip the interactive confirmation prompt
  • --db <PATH>

apollia-os profile reset​

Reset the entire profile (deletes every entry)

Usage: apollia-os profile reset [OPTIONS]

Options:​
  • --confirm - Skip the confirmation prompt
  • --db <PATH>

apollia-os profile schema​

Print the canonical schema (the known structured fields)

Usage: apollia-os profile schema [OPTIONS]

Options:​
  • --db <PATH>

apollia-os profile export​

Dump every entry as a JSON array on stdout (or to --output)

Usage: apollia-os profile export [OPTIONS]

Options:​
  • --output <PATH> - Optional destination file (default: stdout)
  • --db <PATH>

apollia-os profile import​

Import entries from a JSON file produced by export

Usage: apollia-os profile import [OPTIONS] --input <PATH>

Options:​
  • --input <PATH> - Source file (JSON array of ProfileEntry)
  • --overwrite - Overwrite existing entries with the same key
  • --db <PATH>

apollia-os trace​

Print the event-sourced trace of a task

Usage: apollia-os trace [OPTIONS] <TASK_ID>

Arguments:​
  • <TASK_ID> - Task identifier
Options:​

  • --format <FORMAT> - Force JSON output even without global --json

    Default value: human

    Possible values: human, json

apollia-os digest​

Aggregated activity overview (tasks + LLM costs)

Usage: apollia-os digest [OPTIONS]

Options:​

  • --since <SINCE> - Time window: 24h, 7d, or 30d

    Default value: 24h

    Possible values:

    • 24h: Last 24 hours
    • 7d: Last 7 days
    • 30d: Last 30 days

apollia-os completions​

Generate a shell completion script (bash, zsh, fish, powershell, ...)

Usage: apollia-os completions <SHELL>

Arguments:​

  • <SHELL> - Target shell

    Possible values: bash, elvish, fish, powershell, zsh

apollia-os guide​

Short, task-oriented help by theme (chat, governance, audit, ...).

With no topic, lists the available topics.

Usage: apollia-os guide [TOPIC]

Arguments:​
  • <TOPIC> - Topic to display

apollia-os do​

Map a natural-language request to a command (local model), then run it.

Shows the mapped command as a dry-run and asks for confirmation unless -y.

Usage: apollia-os do [OPTIONS] <REQUEST>

Arguments:​
  • <REQUEST> - The request, in natural language
Options:​
  • -y, --yes - Skip the confirmation prompt (non-interactive use)

apollia-os explain​

Explain a command or an error message in plain language (local model)

Usage: apollia-os explain <TEXT>

Arguments:​
  • <TEXT> - The command or error text to explain

This document was generated automatically by clap-markdown.