Docs / Reference

CLI reference

Every ivralo command with its arguments and options, as the code on main defines them. Options marked required must be given; a dash means no default.

Run ivralo --help, or ivralo <command> --help, for the same text on your own machine. The exit codes are on Exit codes.

The session and global options

ivralo with no command opens the full-screen session; it needs a terminal. The options below go before any command: --model and --profile apply to the command that follows, and --session to the session it opens.

ivralo: open the session, or run the command that follows.

Option	Default	What it does
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--model`, `-m`	-	The main model for this run: a pulled tag, or `provider:model` (`anthropic:claude-sonnet-5`, `openai:gpt-5.5`, ...). Keys come from `.env`.
`--profile`	-	`normal` (the default), or `strict`: no shell, no web, no sending, no writes to Google or GitHub, no MCP servers. It only narrows.
`--version`, `-V`	-	Show the version and exit.

Setup

Getting a home, a database and a model in place, and checking them. The install pages walk through them: On a server, From a checkout, Doctor.

ivralo init: One command from a fresh checkout to a working session.

Option	Default	What it does
`--yes`, `-y`	-	Take every default without asking.
`--model`, `-m`	-	The main model: a pulled tag, or `provider:model`.
`--docker`, `--no-docker`	-	Start PostgreSQL with docker compose.
`--pull`, `--no-pull`	-	Pull the Ollama tags that are missing.
`--browser`, `--no-browser`	-	Install the web tools' browser.
`--hooks`, `--no-hooks`	-	Set the git hooks in a checkout.
`--home`	-	Make this directory a home first - the shipped skills, `brand.json`, `workspace/`.
`--server`	-	A server install: no questions (`--yes`), no browser, no Ollama pull, no hooks. The project's install step runs only under a typed `--yes`, and is asked once at a terminal; with neither it is red when `IVRALO.md` declares a language server, a hint when not.
`--model-url`	-	An OpenAI-compatible endpoint's base URL; `--model` is then a name served there.
`--embed-model`	-	The embedding model: `provider:model`, or a name at `--model-url`. A server without one runs with the knowledge index off.
`--postgres`	-	An existing PostgreSQL's URL (`postgresql://user:password@host:5432/db`), written to `.env` and never printed. Or `auto` (docker, else a local PostgreSQL, else the `ivralo[pg]` extra's: ivralo makes one under the home; the default with `--server`). Or `managed` (the same cluster, started and stopped by your service manager).
`--token`	-	Make the local API's token file (`ivralo serve` reads it).
`--workspace`	-	Point the home at an existing repository.
`--trust`	-	Trust the folder init works in (and remember it).
`--git-name`	-	With `--server`: the name ivralo commits as.
`--git-email`	-	With `--server`: ivralo's own git e-mail - never yours.

ivralo doctor: Check that everything ivralo needs is actually here.

ivralo agents: List the specialists and the skills each one owns.

Asking

One request from a script or a pipe, and the local API for clients that are not a terminal. See Local API.

ivralo ask PROMPT...: Run a single request and exit.

Option	Default	What it does
`PROMPT...`	required	What you want done.
`--image`, `-i`	-	Attach an image (repeatable): a file beside you, or one in the workspace.
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--verbose`	-	Show every tool argument in full, not the compact trace.
`--no-stream`	-	Wait for the full answer instead of streaming.
`--plan`	-	Draft a step plan first, show it, then execute it.
`--yes`, `-y`	-	With `--plan`: execute without asking (pipes).
`--format`	`text`	`text` (default), or `json`: one JSON object on stdout, the trace on stderr.
`--quiet`, `-q`	-	Print the plain reply and nothing else.
`--stdin-name`	`stdin.txt`	Where piped text lands in the workspace.
`--no-stdin`	-	Ignore stdin even when it is not a terminal.
`--model`, `-m`	-	The main model for this run: a pulled tag, or `provider:model` (`anthropic:claude-sonnet-5`, `openai:gpt-5.5`, ...). Keys come from `.env`.
`--profile`	-	`normal` (the default), or `strict`: no shell, no web, no sending, no writes to Google or GitHub, no MCP servers. It only narrows.
`--job`	-	Run it as a job: its record outlives this terminal, and `ivralo resume <id>` continues it after a crash.
`--via-api`	-	Send it to the running `ivralo serve` and answer its approvals here.
`--trust`	-	Trust this folder (and remember it): what its `IVRALO.md` declares may then run.
`--changeset`, `--no-changeset`	-	Stage the edits as one changeset: landed only when the declared checks pass.
`--keep-changeset`	-	Stage the edits and keep them staged, never land.

ivralo serve: Run the local API for this workspace until Ctrl+C: loopback only, a token, nothing kept.

Option	Default	What it does
`--port`	-	The loopback port; `IVRALO_API_PORT` (61017) by default.
`--new-token`	-	Replace the token; every client needs the new one.

Working in a repository

Plans, checks, trust, and what each turn changed. See Developer mode.

ivralo plan PROMPT...: Draft a plan for a request, save it as Markdown and print it, without running it - or, with --job, run it as a job that outlives this terminal.

Option	Default	What it does
`PROMPT...`	required	What you want done.
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--json`	-	JSON for scripts.
`--profile`	-	`normal` (the default), or `strict`: no shell, no web, no sending, no writes to Google or GitHub, no MCP servers. It only narrows.
`--job`	-	Run the drafted plan at once as a job - with no review step; `ask --plan --job` shows it first. Its record outlives this terminal (`ivralo resume <id>`).

ivralo verify [PATHS...]: Run the project's format, lint, types and test commands from IVRALO.md, cheapest first.

Option	Default	What it does
`PATHS...`	-	The changed files; what git says changed since `HEAD` when omitted.
`--scope`	`targeted`	`targeted`: the tests the change selects, then one ring wider; `full`: the whole test command.
`--yes`, `-y`	-	Approve the commands that would ask.
`--trust`	-	Trust this folder (and remember it) before running.

ivralo trust [PATH]: Trust a folder: its IVRALO.md's commands, language servers and permissions then apply.

Option	Default	What it does
`PATH`	-	The folder; the current one when omitted.
`--revoke`	-	Forget that the folder was trusted (or said no to).
`--list`	-	List every trusted folder, and say nothing else.
`--yes`, `-y`	-	Trust without a terminal to ask (a script).

ivralo changes: What each turn changed in this repository, newest first - the session's changes panel.

Option	Default	What it does
`--limit`, `-n`	`20`	How many turns to show.
`--json`	-	One JSON object on stdout.
`--hunks`	-	Each file's hunks under their symbol, as the diff viewer has them.

ivralo history [FILE]: The versions kept before a workspace file was overwritten.

Option	Default	What it does
`FILE`	-	A workspace file; every file with history when omitted.

ivralo restore FILE: Bring a kept version of a file back. The current file is kept in history first.

Option	Default	What it does
`FILE`	required	The workspace file to bring back.
`--at`	-	A stamp (or its start); the newest when omitted.

ivralo changeset

ivralo changeset with no subcommand lists this workspace's staged changesets. See Changesets.

ivralo changeset list: The staged changesets: id, how many files, what was asked.

Option	Default	What it does
`--json`	-	One JSON object on stdout.

ivralo changeset show [CHANGESET_ID]: One changeset's files and hunks, as the diff viewer shows them.

Option	Default	What it does
`CHANGESET_ID`	-	The changeset's id, or its start; the one staged if omitted.
`--json`	-	One JSON object on stdout.

ivralo changeset land [CHANGESET_ID]: Land it in your tree through history; refused, nothing written, over your own edits.

Option	Default	What it does
`CHANGESET_ID`	-	The changeset's id, or its start; the one staged if omitted.

ivralo changeset drop [CHANGESET_ID]: Throw the staged edits away; your tree stays exactly as it is.

Option	Default	What it does
`CHANGESET_ID`	-	The changeset's id, or its start; the one staged if omitted.
`--yes`, `-y`	-	Drop it without asking.

ivralo changeset release CHANGESET_ID: Clear the mark of a turn that no longer runs, so the changeset can be landed or dropped.

Option	Default	What it does
`CHANGESET_ID`	required	The changeset's id, or its start.

Sessions and runs

A run is one request and everything the team did for it. These commands list, open and export them. See Observability and Why.

ivralo sessions: List recent conversations, newest first.

Option	Default	What it does
`--limit`, `-n`	`20`	How many to show.

ivralo new: Start a fresh session. The old one stays in the database.

ivralo compact: Summarize the session and hide older turns from the model's context.

Option	Default	What it does
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--focus`	-	What the summary should pay particular attention to.
`--keep`	`2`	How many of the newest runs stay visible for continuity.

ivralo runs: List the session's runs, newest first: what was asked, who did it, what it cost.

Option	Default	What it does
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--limit`, `-n`	`20`	How many to show.

ivralo trace [RUN]: Open a run: every tool call, its arguments, and what it returned.

Option	Default	What it does
`RUN`	`last`	A run id prefix (8+ characters), or `last`.
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--json`	-	The flat tool-call list as JSON.
`--tail`	`12`	Lines of each output to show.
`--html`	-	Write the run as one self-contained HTML file - timeline, every call, the full output - instead of printing it.
`--out`	-	Where `--html` writes; default: `workspace/.ivralo/traces/`.

ivralo why RUN CLAIM: Where a claim came from: the chain of recorded facts behind it.

Option	Default	What it does
`RUN`	required	A run id prefix (8+ characters), or `last`.
`CLAIM`	required	What to trace: a number ("18%") or a phrase.
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--json`	-	The chain as one JSON object on stdout.

ivralo export [SESSION]: Write a whole conversation as one file: every turn, its tool calls, the replies.

Option	Default	What it does
`SESSION`	`last`	A session id (8+ characters), or `last` for the active one.
`--format`	`html`	`html` (one self-contained page) or `md`.
`--out`	-	Where to write; default: `workspace/.ivralo/exports/`.

Record and replay

A cassette is a stored run's tool answers, masked, kept under .ivralo/cassettes/. See Record and replay.

ivralo record [RUN]: Write a stored run as a cassette in .ivralo/cassettes/ and print its path.

Option	Default	What it does
`RUN`	`last`	A run id prefix (8+ characters), or `last`.
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.

ivralo replay [RUN]: Run a stored run's prompt again with every tool answered from its cassette.

Option	Default	What it does
`RUN`	`last`	A run id prefix (8+ characters), or `last`.
`--tools`	`mocked`	What the tools do: `mocked` answers every call from the cassette.
`--session`, `-s`	-	Attach to a specific session id instead of the shared one. Use this to run two terminals on separate conversations.
`--json`	-	The report as one JSON object on stdout.

Jobs

A job is work whose record outlives the terminal that started it. See Jobs.

ivralo jobs with no subcommand lists this workspace's jobs.

ivralo jobs list: List this workspace's jobs: id, state, age, step in flight, what a parked one waits on.

ivralo jobs run: Run this workspace's next job, then exit - what the OS scheduler calls.

ivralo job JOB_ID: One job in full: its state, its lease, the question it is parked on, its log.

Option	Default	What it does
`JOB_ID`	required	The job's id, from `ivralo jobs`.

ivralo cancel JOB_ID: Stop a running, parked or queued job and record it as cancelled.

Option	Default	What it does
`JOB_ID`	required	The job's id, from `ivralo jobs`.

ivralo resume JOB_ID: Continue a job: after a crash from its last delivered step, saying which step restarts and what the attempt before it left; a queued one starts; a parked one goes on with the answer given here - without one it says its question and exits 1, changing nothing.

Option	Default	What it does
`JOB_ID`	required	The job's id, from `ivralo jobs`.
`--approve`	-	A parked job: yes, this call.
`--approve-job`	-	A parked job: yes, and every edit for the rest of this job.
`--reject`	-	A parked job: no - the note tells the model what to do instead.

ivralo bisect: Find the commit that broke a command: a job that tests commits between --good and --bad in a worktree of its own, never your checkout. Exit 0 when it ends, 1 when it fails.

Option	Default	What it does
`--good`	required	A commit where the command passes.
`--bad`	`HEAD`	A commit where it fails.
`--command`	-	What to run at each commit; the declared test command if empty.
`--steps`	`0`	The most commands to run; `IVRALO_BISECT_STEPS` if 0.

Schedules

ivralo schedule with no subcommand lists the schedules. A schedule is a cron entry on Linux and macOS and a schtasks task on Windows. See Schedules.

ivralo schedule list: List the schedules, whether the OS still has them, and their last run.

ivralo schedule add NAME [REQUEST...]: Register a request with the OS scheduler and remember it in schedules.json.

Option	Default	What it does
`NAME`	required	A name: letters, digits, dashes.
`--every`	required	`daily HH:MM`, `weekdays HH:MM`, `weekly <mon..sun> HH:MM`, `monthly <1-31> HH:MM`, `hourly`.
`REQUEST...`	-	What to do, as you would ask.
`--mail-to`	-	Recipients this schedule may e-mail (repeatable). Without it, it cannot send.
`--notify`	-	This schedule may post to the configured Telegram or Slack chat.
`--yes`	-	Replace an existing schedule unasked.
`--jobs`	-	Run `ivralo jobs run` for this workspace instead of a request: the next queued job starts each time.

ivralo schedule remove NAME: Unregister the OS task and forget the schedule; its run logs stay.

Option	Default	What it does
`NAME`	required	The schedule to delete.
`--yes`	-	Skip the prompt.

ivralo schedule run NAME: Run a schedule's request now, unattended - what the OS task calls.

Option	Default	What it does
`NAME`	required	The schedule to run now.

ivralo schedule log NAME: The last runs: when, ok or failed, seconds, files, the reply's first line.

Option	Default	What it does
`NAME`	required	The schedule whose runs to show.
`--limit`	`10`	How many runs, newest first.

Incidents

See Investigating an incident and A pilot on your incidents.

ivralo incident [BUNDLE]: Investigate an incident from its evidence bundle and file a report.

Option	Default	What it does
`BUNDLE`	`incident/`	The evidence bundle: a directory in the workspace.
`--format`	`text`	`text` (default), or `json`: the report's object on stdout, the trace on stderr.
`--hosted`	-	Let a model that leaves the machine read the evidence, for this run; it needs `IVRALO_INCIDENT_MASK=true`, so the model reads placeholders.
`--session`, `-s`	-	The session to run in: a fresh one named after the incident by default; `shared` joins the shared session, any other id continues that session.

ivralo pilot run PACK: Investigate every incident of the pack and score each report against its known cause.

Option	Default	What it does
`PACK`	required	The pack: a directory of resolved incidents.
`--repository`	-	The repository the revisions are in (default: the workspace).
`--out`	-	Where the report goes, outside the repository (default: `<pack>/.pilot/<stamp>/`).
`--format`	`text`	`text` (default), or `json`: the report on stdout.
`--hosted`	-	Let a model that leaves the machine read the evidence.
`--fail-under`	-	The bar: exit 1 when fewer than this percent of the incidents matched.

Knowledge, skills and memory

See The knowledge index and Skills.

ivralo index: Embed the workspace's documents into the knowledge index.

Option	Default	What it does
`--rebuild`	-	Start this workspace's index over instead of updating what changed.
`--all`	-	With `--rebuild`: every workspace in the database, and the vector table itself (a changed embedding size, a moved workspace's old rows).
`--code`	-	Build the code index instead: symbols and git history, no database.
`--semantic`	-	With `--code`: then embed the code, chunked by symbol, for `semantic_code_search`.

ivralo search QUERY...: Search the knowledge index by hand: the hits the Librarian would get.

Option	Default	What it does
`QUERY...`	required	What to look for, as you would ask.
`--limit`, `-n`	`0`	Hits to show; `IVRALO_KNOWLEDGE_RESULTS` when 0.
`--json`	-	The hits as JSON, for scripts.

ivralo skills

ivralo skills with no subcommand lists the installed skills and whether they validate.

ivralo skills assign NAME: Grant a skill to one or more specialists via the local overlay.

Option	Default	What it does
`NAME`	required	Skill to grant.
`--agent`, `-a`	required	Specialist key to grant it to (repeatable).

ivralo skills unassign NAME: Remove a skill's overlay assignment.

Option	Default	What it does
`NAME`	required	Skill whose overlay grant to drop.

ivralo skills create NAME: Scaffold a new skill package that validates as written.

Option	Default	What it does
`NAME`	required	Name for the new skill (lowercase-hyphenated).
`--agent`, `-a`	-	Specialist key to grant it to (repeatable; local shelf only).
`--shipped`	-	Scaffold into the committed `skills/` shelf instead of `skills.local/`.
`--scripts`	-	Include a `scripts/` directory.
`--references`	-	Include a `references/` directory.

ivralo skills lint [NAME...]: Check skills for the traps that cost real answers.

Option	Default	What it does
`NAME...`	-	Skills to lint; all when omitted.
`--strict`	-	Exit 1 when an error-level finding exists.
`--shelf`	-	`shipped` or `local`; both when omitted.
`--fix`	-	Quote an unreadable name/description on the local shelf.

ivralo skills install SOURCE: Install a skill from GitHub into the local shelf.

Option	Default	What it does
`SOURCE`	required	`owner/repo[/sub/path][@ref]`, or a pasted GitHub URL.
`--agent`, `-a`	-	Specialist key to grant it to (repeatable).
`--yes`	-	Skip the prompt for a fresh install. Updates always ask.

ivralo skills update NAME: Re-fetch an installed skill from its recorded source. Always asks.

Option	Default	What it does
`NAME`	required	Installed skill to re-fetch from its source.

ivralo skills remove NAME: Delete a local skill and its overlay grant.

Option	Default	What it does
`NAME`	required	Local skill to delete, grant included.
`--yes`	-	Skip the prompt.

ivralo memory

ivralo memory with no subcommand lists the memories.

ivralo memory list: List the memories.

ivralo memory forget MEMORY: Forget one memory.

Option	Default	What it does
`MEMORY`	required	A memory id, or enough of its start.

ivralo memory clear: Forget everything remembered about you.

Option	Default	What it does
`--yes`, `-y`	-	Do not ask.

Integrations

ivralo mcp

ivralo mcp with no subcommand lists the configured servers. See MCP servers.

ivralo mcp list: List the configured MCP servers.

ivralo mcp recipes: The known servers: what each gives, what it needs, who carries it.

ivralo mcp add [NAME]: Declare one MCP server, validated against the roster.

Option	Default	What it does
`NAME`	-	Server name (also the toolkit label); a recipe's name by default.
`--recipe`	-	Start from a known server: see `ivralo mcp recipes`.
`--command`	-	Executable for a stdio server. On Windows npx servers need: `--command cmd --arg /c --arg npx --arg -y --arg "<package>"`
`--arg`	-	Argument for the command (repeatable, kept unsplit).
`--url`	-	Endpoint of a remote server (streamable-http default).
`--transport`	-	`stdio`, `sse` or `streamable-http` (`http` is an alias).
`--env`	-	`KEY=VALUE` for the server (repeatable; `${VAR}` expands).
`--header`	-	`KEY=VALUE` HTTP header (repeatable; `${VAR}` expands).
`--agent`, `-a`	-	Specialist key that carries its tools (repeatable).
`--timeout`	`30`	Read timeout in seconds.
`--include-tool`	-	Only expose these tools (repeatable).
`--exclude-tool`	-	Hide these tools (repeatable).
`--prefix`	-	Prefix for tool names, against collisions.
`--disabled`	-	Keep it in the file but attach it to nobody.
`--yes`	-	Overwrite an existing entry unasked.

ivralo mcp remove NAME: Delete one server from the file.

Option	Default	What it does
`NAME`	required	Server entry to delete.
`--yes`	-	Skip the prompt.

ivralo mcp test NAME: Connect to a server for real and list its tools.

Option	Default	What it does
`NAME`	required	Server to connect to.

ivralo google

See Google Workspace.

ivralo google login: Consent once in the browser; the token lands at the home and is refreshed from then on.

Option	Default	What it does
`--yes`, `-y`	-	Open the browser without asking first.

ivralo google status: What is in place, and the first thing to fix.

ivralo google logout: Forget the token. The next login asks for consent again.

Evals

ivralo eval runs ivralo's behavioural evals against a real model. It is a contributor's tool, documented with its options on Evals.