Commands
Host helper commands, Facio CLI commands, and runtime slash commands.
Facio has three command layers. They solve different jobs and should not be confused.
| Layer | Where it runs | Use it for |
|---|---|---|
| Quickstart helper | Host install directory, ./facio ... | Docker Compose lifecycle: status, logs, update, scale, up, down. |
| Facio CLI | Inside a Python/installed Facio environment | Local init, gateway, chat, channel login, provider OAuth. |
| Slash commands | Placet, Telegram, Discord, Slack, CLI chat | Runtime control of the active agent. |
Quickstart helper
The quickstart writes a host-side ./facio helper into the install directory. It wraps Docker Compose and includes the base compose file, optional override file, and generated scale file.
| Command | Meaning |
|---|---|
./facio status | Show Docker Compose service status. |
./facio logs [service...] | Follow logs, for example ./facio logs facio-1. |
./facio restart [service...] | Restart one service or the whole stack. |
./facio update | Pull latest images and recreate services without changing replica count. |
./facio scale N | Run N Facio agents with stable hostnames facio-1, facio-2, and so on. |
./facio render [N] | Regenerate docker-compose.scale.yml only. |
./facio config | Print the merged Compose config. |
./facio up | Start the stack idempotently. |
./facio down | Stop the stack. |
Scaling writes docker-compose.scale.yml. Agent #1 keeps the base service; additional agents extend it and override only hostname, visible Placet name, and management URL.
Facio CLI
The Python CLI is mostly for local development, embedding, and direct runtime testing. The Docker quickstart remains the recommended way to run Facio as an operator-facing service.
| Command | Use it for |
|---|---|
facio onboard | Create or refresh config.json, optionally with --wizard, --workspace, or --config. |
facio agent | Send a direct message to the agent with --message, --session, --workspace, and --logs. |
facio serve | Start only the OpenAI-compatible HTTP API surface. |
facio gateway | Start the full gateway with channels, management API, cron, MCP, and Placet registration. |
facio status | Inspect config, workspace, selected model, and provider credential status. |
facio provider | Run provider OAuth commands such as provider login. |
Runtime slash commands
Slash commands are channel-visible runtime controls. Placet syncs structured command metadata; Telegram and Discord expose command menus where supported.
| Command | Purpose |
|---|---|
/new | Start a new conversation. |
/stop | Stop the current task. |
/restart | Restart the bot. |
/status | Show runtime status. |
/history [n] | Show recent conversation messages. |
/check | Run a system diagnostic for tools, providers, MCP, and security. |
/settings | Manage model and provider settings, primarily in Placet. |
/settings advanced | Adjust temperature, limits, retries, concurrency, and related tuning. |
/settings keys | Manage API keys and credentials from the operator UI. |
/credentials list/add/rm/expose/unexpose | Manage the credential store and shell exposure whitelist. |
/continue | Resume a turn that hit the iteration limit. |
/abort | Discard a pending resume state. |
/audit tail/run/stats | Inspect audit records. |
/goal text/status/pause/resume/clear | Manage a persistent multi-turn goal. |
/subgoal or /checklist | Show or edit the active goal checklist. |
/heartbeat status/pause/resume/clear | Manage heartbeat runtime state. |
/learn instruction | Teach Facio a durable instruction. |
/reflect | Trigger Reflection memory consolidation. |
/reflection-log [sha] | Show the latest Reflection change. |
/reflection-restore [sha] | Restore Reflection memory to an earlier version. |
/guard | Manage guardrail topics and guardrail state. |
/policy, /allow, /deny | Manage tool-call approval policy rules. |
/improve | Manage self-improvement runs: status, review, diff, approve, reject, rollback. |
/help | Show available commands. |
Reflection and Improve
Reflection and Improve are related but separate workflows.
Reflection consolidates useful learnings into memory. Use /reflect to run consolidation, /reflection-log [sha] to inspect recent Reflection changes, and /reflection-restore [sha] to restore an earlier version.
Improve reviews the agent-owned implementation and creates inspectable self-improvement proposals. A manual /improve run reviews the configured scopes and phases, captures proposed file changes through sandboxed file tools, stores reports and diff artifacts, and waits for review unless the configured mode allows auto-apply. Operators can inspect with /improve diff [id], apply with /improve apply [id], cancel with /improve cancel [id], and roll back an applied run with /improve rollback <id>.
Improve does not rely on a final LLM JSON blob as the source of truth for changes. The proposal is based on tracked sandbox writes and versioned artifacts so operators can inspect, approve, reject, and roll back concrete diffs.
Provider OAuth commands
OAuth-backed providers are not configured with API keys. The CLI exposes provider login flows for providers such as OpenAI Codex and GitHub Copilot:
facio provider login openai-codex
facio provider login github-copilotIn Placet, OAuth flows can also be relayed through the operator UI where supported.
Management command endpoints
External operator tooling can call a small set of management command endpoints:
| Endpoint | Action |
|---|---|
POST /api/v1/commands/stop | Stop the current task. |
POST /api/v1/commands/restart | Restart the runtime. |
POST /api/v1/commands/new | Start a new conversation. |
POST /api/v1/commands/reflect | Trigger Reflection. |
GET /api/v1/commands/status | Read runtime status. |
These require the management bearer token.