CLI reference

Install#

bash
pip install -e ".[dev]"       # dev + test stack
pip install -e ".[mcp]"       # include MCP client support

First-time setup — easiest path:

bash

1	`scaiflux setup`

Walks through three prompts: pick the ScaiGrid endpoint (ScaiLabs default or a custom URL), paste a ScaiGrid API key (sgk_live_...), and pick a default model from the discovered catalog. Optionally scaffolds .scaiflux.json + SCAIFLUX.md in the current directory. Re-runnable any time.

The REPL detects first-run automatically: launching scaiflux with no credentials file and a TTY will offer to run the wizard before dropping you in. Scripted invocations get a hint and continue.

For headless or already-scripted setups, drive login directly:

bash
# Interactive (ScaiKey OAuth PKCE, opens a browser):
export SCAIGRID_BASE_URL="https://scaigrid.example.com"
export SCAIKEY_BASE_URL="https://scaikey.example.com"
export SCAIKEY_TENANT="your-tenant"
export SCAIKEY_CLIENT_ID="scaiflux-cli"
scaiflux login

# Headless ScaiGrid API key:
scaiflux login --scaigrid-url https://scaigrid.example.com --api-key sgk_live_...

# BYO OpenAI-compatible backend (no ScaiGrid):
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://compat.example/v1"

The session and discovered model catalog live in ~/.scaiflux/credentials.json (mode 0600); scaiflux logout clears it.

Top-level subcommands#

Command	What it does
`scaiflux setup`	First-run wizard — endpoint + API key + default model + optional workspace scaffold
`scaiflux login`	Authenticate via ScaiKey OAuth PKCE (or `--api-key sgk_live_...`)
`scaiflux logout`	Remove `~/.scaiflux/credentials.json`
`scaiflux prompt <text>`	Run a one-shot prompt, streaming the response
`scaiflux repl`	Launch the interactive REPL with tab-completed slash commands
`scaiflux serve`	Run as an NDJSON-over-stdio service driven by an external controller (see `SERVE.md`)
`scaiflux status`	Snapshot of workspace + config + session state
`scaiflux doctor`	Health checks (Python, credentials, workspace, config)
`scaiflux sandbox`	Container-marker detection report
`scaiflux init`	Scaffold `.scaiflux.json` + `SCAIFLUX.md` + `.gitignore` entries
`scaiflux system-prompt`	Print the assembled system prompt
`scaiflux dump-manifests`	Dump tool + slash-command catalogs as JSON
`scaiflux bootstrap-plan`	Print the 5-phase bootstrap plan
`scaiflux plugin {list,install,enable,disable,uninstall,update}`	Manage plugins
`scaiflux agents {list,show <name>}`	List configured sub-agents
`scaiflux mcp {list,show <name>,status}`	List + probe configured MCP servers
`scaiflux skills {list,show <name>}`	List discovered skills
`scaiflux session {list,replay,fork}`	Inspect, replay, or branch stored sessions
`scaiflux version`	Print the ScaiFlux version

Session subcommand#

bash
scaiflux session list                                # all sessions in this workspace
scaiflux session replay <id|latest|path>             # print the transcript
scaiflux session fork <id|latest> --at <turn>        # branch a new session at turn N

fork defaults to a full copy when --at is omitted; --at 0 keeps just the first message.

`prompt` flags#

Flag	Default	Purpose
`--model, -m`	(from session)	Frontend model slug (see `scaiflux doctor` for the discovered list)
`--max-tokens`	`1024`	Cap on output tokens per turn
`--workspace, -w`	`.`	Workspace root (tool execution + session files)
`--permission-mode`	`danger-full-access`	One of `read-only` / `workspace-write` / `danger-full-access` / `prompt` / `plan`
`--dangerously-skip-permissions`	off	Force `danger-full-access` unattended
`--max-iterations`	`20`	Max tool-loop iterations
`--resume <id\|latest\|path>`	—	Resume an existing session
`--output-format {text,json}`	`text`	Text streams directly; JSON emits a single envelope with `message`, `model`, `usage`, `estimated_cost`, `tool_uses`, `tool_results`, `auto_compaction`
`--allowedTools <csv>`	all	Comma-separated tool-name filter

REPL slash commands#

Type /help inside the REPL for the full list. Every command is real — no stubs. Categories:

session: /help, /exit//quit, /clear, /compact, /save <key> [--global], /export [json|jsonl|md] [path], /tasks, /team, /cron, /session {list,resolve,replay,fork,delete,clear}
project: /init, /memory [edit [<file>]], /diff, /files, /release-notes [N], /commit [run], /pr [run], /issue run <subject>
config: /model, /mode, /config, /hooks, /providers, /poolnoodle on|off|status (easter egg persona 🛟)
tools: /sandbox, /agents, /subagent, /skills, /mcp, /plugin, /desktop, /review, /advisor, /insights, /security-review
debug: /version, /status, /doctor, /system-prompt, /cost, /usage, /stats, /context, /telemetry [tail N]

For a narrative tour of the REPL experience (session picker, ESC interrupt, context-usage bar, Poolnoodle mode, etc.), see REPL_WALKTHROUGH.md.

Serve mode (remote control)#

For programmatic orchestration — e.g. ScaiForge driving a sandboxed ScaiFlux instance — use scaiflux serve. The process speaks NDJSON over stdio: one JSON command per line on stdin, one JSON event per line on stdout. Stderr stays for human-readable logs.

bash
scaiflux serve --workspace ./project --model scailabs/poolnoodle-omni

One process == one session. Permissions are always proxied to the controller; on deny the model receives a synthetic tool-error and can adapt in-turn (the turn isn't aborted). The wire schema (scaiflux/cli/protocol.py) is the contract — extra="forbid" on both write and read, with PROTOCOL_VERSION in the ready event.

Full reference, event tables, and an end-to-end transcript: SERVE.md.

Workflow run mode (opt-in): /commit run pipes the generated message into git commit -F -. /pr run parses the first line as the PR title, the rest as the body, and invokes gh pr create. /issue run <subject> calls gh issue create with the generated body. The non-run form just renders the suggestion.

Plan mode#

Start with --permission-mode plan to get "think first, execute after I nod" behavior. The model is told (via a plan-mode stanza in the system prompt) that writes, shell commands, and other mutating tools will be denied by the enforcer — so it should explore the workspace, draft a numbered plan, and call the exit_plan_mode tool with that plan. The plan is printed to stderr for your review; answering y flips the runtime to workspace-write and lets execution proceed. Plan mode is only registered at bootstrap, so entering it via /mode plan mid- session won't surface exit_plan_mode — restart to pick it up.

Config hierarchy#

Later sources override earlier ones:

User — ~/.scaiflux/settings.local.json
Project — <ws>/.scaiflux.json
Local — <ws>/.scaiflux/settings.local.json

Scalars replace; dicts merge recursively; permissions.allow/deny/ask and hooks.* lists concatenate.

Auto-compaction#

Configurable via the SCAIFLUX_AUTO_COMPACT_INPUT_TOKENS env var (default 100 000). When cumulative input tokens cross the threshold, the runtime retains the last 4 messages, records an AutoCompactionEvent in the JSON prompt output, and continues.

Project memory#

Files auto-loaded into the system prompt (walked up from the workspace):

SCAIFLUX.md
SCAIFLUX.local.md
.scaiflux/instructions.md