# CLI Reference The `opensquilla` CLI is the fastest way to configure, run, inspect, and automate OpenSquilla. Run: ```sh opensquilla --help opensquilla --help ``` ## Main Commands | Command | Purpose | | --- | --- | | `opensquilla init` | Initialize a workspace. | | `opensquilla doctor` | Diagnose readiness and print recovery steps. | | `opensquilla uninstall` | Remove OpenSquilla; keeps your data by default (`--purge-*` to delete). | | `opensquilla onboard` | Run or inspect first-run setup. | | `opensquilla configure` | Reconfigure provider, router, channels, search, image generation, or memory embedding. | | `opensquilla gateway` | Run and manage the gateway server. | | `opensquilla chat` | Start interactive terminal chat. | | `opensquilla agent` | Run a single automation-friendly agent turn. | | `opensquilla code-task` | Run a guarded coding task through Coding mode's host workflow. | | `opensquilla sessions` | List, inspect, resume, abort, delete, or export sessions. | | `opensquilla skills` | List, search, view, install, update, publish, and inspect skills. | | `opensquilla memory` | Inspect and maintain memory. | | `opensquilla channels` | Configure and inspect messaging channels. | | `opensquilla providers` | Configure and inspect LLM providers. | | `opensquilla search` | Configure and use web search. | | `opensquilla sandbox` | Inspect or change default sandbox posture. | | `opensquilla cron` | Manage scheduled OpenSquilla runs. | | `opensquilla cost` | Inspect usage and estimated cost. | | `opensquilla diagnostics` | Enable or disable runtime diagnostics logging. | | `opensquilla replay` | Replay a recorded turn from the decision log. | | `opensquilla migrate` | Import state from external agent runtimes. | | `opensquilla models` | Inspect available models. | | `opensquilla agents` | Manage durable agents. | | `opensquilla mcp-server` | Run the OpenSquilla MCP server bridge. | | `opensquilla swebench` | Run optional SWE-bench solve/eval workflows. | | `opensquilla dist` | Emit a reproducible workspace-state inventory. | | `opensquilla reset` | Reset a session and flush memory synchronously. | ## Run Surfaces Web UI and gateway: ```sh opensquilla gateway run opensquilla gateway start --json opensquilla gateway status opensquilla gateway restart opensquilla gateway stop ``` Terminal chat: ```sh opensquilla chat opensquilla chat --model gpt-5.4-mini opensquilla chat --session opensquilla chat --standalone --workspace /path/to/project ``` Terminal chat uses the stable Python-native terminal backend by default. OpenTUI is a preview backend selected explicitly with `OPENSQUILLA_TUI_BACKEND=opentui` when evaluating that backend. Normal terminal chat does not require Bun or OpenTUI node modules. The OpenTUI preview is for source checkouts with local Bun dependencies installed: ```sh bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package OPENSQUILLA_TUI_BACKEND=opentui uv run opensquilla chat ``` Legacy backend values are rejected before launch. Read [`tui.md`](tui.md) for terminal chat usage and [`features/tui-frontend.md`](features/tui-frontend.md) for backend architecture, plugin slots, Router HUD, and replay benchmark workflow. Web chat and the CLI gateway TUI support `/meta` for manual MetaSkill launch: `/meta` lists available workflows and `/meta ` runs one. Channel surfaces can list MetaSkills with `/meta`, but they do not launch MetaSkill runs directly. Standalone CLI chat requires gateway mode for `/meta`. One-shot automation: ```sh opensquilla agent -m "Review the current directory" opensquilla agent --json -m "Return a short machine-readable summary" opensquilla agent --workspace /path/to/project --workspace-strict -m "Inspect this repo" opensquilla agent --timeout 600 --max-iterations 30 -m "Run a bounded investigation" ``` Useful automation flags: | Flag | Purpose | | --- | --- | | `--workspace` | Set the workspace root. | | `--workspace-strict` | Restrict read-side file tools to the workspace. | | `--workspace-lockdown` | Contain writes to workspace or scratch directory. | | `--scratch-dir` | Place temporary scripts/logs/candidate patches in a known directory. | | `--timeout` | Set total agent wall-clock timeout. | | `--max-iterations` | Bound the model/tool loop. | | `--max-provider-retries` | Bound transient provider retries. | | `--length-capped-continuations` | Bound automatic continuations after length-limited provider output. | | `--thinking` | Override reasoning level. | | `--permissions` | Select restricted, bypass, or full permission posture. | | `--transcript-path` | Write a JSONL transcript for automation. | | `--usage-path` | Write usage JSON. | | `--session-db-path` | Persist session replay across invocations. | ## Coding Mode and Code-Task Coding mode routes code modification work through the `code-task` workflow. It is designed for trusted repositories: `code-task` runs an OpenSquilla agent on the host, may install dependencies, and is not an OS sandbox. ```sh opensquilla code-task solve --repo /path/to/repo --task-file task.md --yes opensquilla code-task solve --repo https://github.com/org/project.git --issue 123 opensquilla code-task solve --verification-mode scratch --task "Create a small CLI parser" --yes opensquilla code-task solve --repo /path/to/app --task-file task.md --verification-mode build --yes ``` Use exactly one task source: `--issue`, `--task`, or `--task-file`. Non-interactive callers must pass `--yes` to acknowledge the trusted-host boundary. Work happens in an isolated run directory under the OpenSquilla state tree; the source repo is updated only after the workflow collects and verifies a productive change. `--verification-mode red-green` is the default for existing repositories. `--verification-mode build` is for app or artifact delivery checks. `--verification-mode scratch` creates an empty throwaway repo and must not be combined with `--repo`. ## SWE-Bench `opensquilla swebench` is an optional evaluation surface, not part of the normal install path. It requires Docker plus the `swebench` extra. ```sh uv tool install --python 3.12 "opensquilla[recommended,swebench] @ https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc3/opensquilla-0.5.0rc3-py3-none-any.whl" opensquilla swebench pull django__django-16429 --dataset verified opensquilla swebench solve django__django-16429 --dataset verified --json opensquilla swebench eval predictions.jsonl --dataset verified ``` Use `opensquilla code-task` for trusted real-repository coding tasks when you do not need the Docker-based SWE-bench harness. ## Configuration Commands Provider and router: ```sh opensquilla onboard opensquilla onboard status opensquilla configure provider --provider openrouter --api-key-env OPENROUTER_API_KEY opensquilla configure router --router recommended opensquilla providers list opensquilla providers configure openrouter opensquilla providers status ``` Search: ```sh opensquilla search list opensquilla search configure duckduckgo opensquilla search query "latest OpenSquilla release" opensquilla configure search --search-provider duckduckgo ``` Channels: ```sh opensquilla channels types opensquilla channels describe telegram opensquilla channels add telegram --name personal opensquilla channels list opensquilla channels status opensquilla channels enable personal opensquilla channels disable personal opensquilla channels restart personal opensquilla channels remove personal ``` Raw config: ```sh opensquilla config get llm.provider opensquilla config set gateway.port 18791 ``` More detail: - [`configuration.md`](configuration.md) - [`providers-and-models.md`](providers-and-models.md) - [`search.md`](search.md) - [`channels.md`](channels.md) ## Skills and Meta-Skills ```sh opensquilla skills list opensquilla skills search pdf opensquilla skills view pdf-toolkit opensquilla skills install opensquilla skills update --all opensquilla skills uninstall opensquilla skills inspect meta-skill-creator opensquilla skills meta proposals list opensquilla skills meta runs list opensquilla skills meta runs show opensquilla skills meta runs steps opensquilla skills meta runs replay --dry-run ``` Use `skills inspect` when you want to see the compiled step plan for a meta-skill before invoking it. MetaSkills are manual-only by default. In web chat and the CLI gateway TUI, run `/meta` to list workflows and `/meta ` to launch one. Natural-language auto-triggering is disabled unless `meta_skill.auto_trigger = true` is set in configuration for compatibility with older behavior. Read: - [`features/skills.md`](features/skills.md) - [`features/meta-skills.md`](features/meta-skills.md) - [`features/meta-skill-user-guide.md`](features/meta-skill-user-guide.md) - [`authoring/meta-skills.md`](authoring/meta-skills.md) ## Sessions and History ```sh opensquilla sessions list opensquilla sessions show opensquilla sessions resume opensquilla sessions abort opensquilla sessions export opensquilla sessions delete ``` Read: [`sessions.md`](sessions.md) ## Memory ```sh opensquilla memory status opensquilla memory index opensquilla memory list opensquilla memory search "preference" opensquilla memory show opensquilla memory dream opensquilla memory flush-session opensquilla memory repair list opensquilla memory raw-fallbacks list ``` Read: [`features/memory.md`](features/memory.md) ## Durable Agents and Scheduling ```sh opensquilla agents list opensquilla agents add research --name Research --workspace /path/to/research opensquilla agents delete research opensquilla cron list opensquilla cron add --every 1h --text "Summarize important updates" --name hourly-summary opensquilla cron status opensquilla cron runs ``` Read: - [`agents.md`](agents.md) - [`scheduling.md`](scheduling.md) ## Cost, Diagnostics, and Replay ```sh opensquilla cost opensquilla diagnostics status opensquilla diagnostics on opensquilla diagnostics off opensquilla replay --session --turn ``` Use diagnostics and replay when you need to understand why a turn behaved a certain way. Read: - [`usage-and-cost.md`](usage-and-cost.md) - [`diagnostics-and-replay.md`](diagnostics-and-replay.md) ## MCP Server Bridge ```sh opensquilla mcp-server run opensquilla mcp-server run --gateway ws://localhost:18792/ws ``` Read: [`mcp-server.md`](mcp-server.md) ## Uninstall ```sh opensquilla uninstall --dry-run # preview what is removed and kept opensquilla uninstall # remove the program, keep your data opensquilla uninstall --purge-state # also delete runtime state (sessions, logs, cache) opensquilla uninstall --purge-config # also delete config and secrets opensquilla uninstall --purge-all # delete ALL OpenSquilla data (needs a typed phrase) opensquilla uninstall --json # machine-readable plan/result ``` Your data is kept by default; `--purge-*` opts into deletion, and `--purge-all` requires typing a confirmation phrase (or `--confirm-purge-all "delete everything"` on non-interactive surfaces). The running gateway is drained and stopped before anything is removed, and deletion is contained to the OpenSquilla home — a relocated or shared root is refused. Docker and desktop installs print guided removal steps instead of deleting an image layer or app bundle; source installs never delete your checkout. --- [Docs index](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)