Skip to content

Developers · CLI

Work where your project lives.

The spiron CLI opens an interactive terminal agent in your project. Use a one-shot prompt for a bounded task, or continue an existing session.

Executable
spiron
Script output
JSONL agent events
On this page3 sections
  1. 01Launch
  2. 02Prompts and sessions
  3. 03Tools and configuration

01 · Launch

Start with your installed build.

Shell · CLI discovery and sign-in
spiron --help
spiron version --json
spiron login
spiron whoami
spiron

These commands assume spiron is already installed and on your PATH. With no subcommand, it opens the interactive TUI in the current project. Sign-in may require completing the device flow in your browser.

Building from a repository checkout instead? With the Rust toolchain and project prerequisites available, inspect the CLI with:

Shell · from the repository root
cargo run -p spiron-cli --bin spiron -- --help

02 · Prompt and continue

Choose the output your caller needs.

Shell · prompt examples
spiron -p "Read this project and summarize how to run its tests. Do not edit files."
spiron --json -p "List the top-level directories. Do not edit files."
spiron --session "$SPIRON_SESSION_ID"

-p supplies a one-shot user message. --json emits agent stream events as JSON Lines; it is not one JSON result object. For the last command, set SPIRON_SESSION_ID to a real existing session ID.

A request to avoid edits guides the agent; it does not replace tool permissions. Restrict access to match the task and inspect the result yourself.

03 · Configure

Make the project boundary explicit.

Selected CLI options
OptionPurpose
--workdir PATHSelect the project root before discovering instructions and skills.
--mcp-config PATHLoad JSON stdio MCP server mounts using a mcpServers object.
--skills-dir PATHAdd a skill directory; workspace .agents/skills is also discovered.
--profile PATH_OR_NAMESelect a TOML config path or a named profile in the private state directory.
--state-dir PATHOverride the private config, login, and session root; takes precedence over SPIRON_HOME.

Only mount MCP servers you trust. Keep private state out of the project repository. Use spiron --help as the reference for the build you are actually running; flags in main may be newer.

Try it

Give the agent a checkable task.

Start read-only. Review the result before granting broader access.