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