Command reference

Run agent-cli --help for launch options. Inside a session, /help lists commands and /help NAME describes one. Availability can depend on the active provider, dialect, and enabled tools.

Launch options

Launch defaults and additional controls

Shell execution, project-instruction discovery, and filesystem skills are enabled by default; persistent GHCi is disabled. Desktop control defaults to enabled only for interactive, non-one-shot runs with a TTY, where supported. A prompt supplied with -p does not enable desktop control by default, even from a terminal. Provider and model selection can inherit saved configuration, so specify both when a repeatable automation depends on a particular backend.

Code mode is a model-facing tool orchestration capability, not the documentation renderer or a JavaScript application requirement. Internal managed-turn flags are intended for harness components rather than ordinary shell automation.

Argument validation and diagnostics

--prompt TEXT is the long form of -p TEXT. Choose exactly one prompt source: -p, --prompt-file, or the internal --managed-turn-file. Do not combine --resume and --worktree: resume reopens an existing session, whereas worktree creates a new checkout. Repeated run options are applied in order; the last assignment wins.

Turn, concurrency, and compaction limits require positive integers, not zero, fractions, or an unlimited sentinel. The default model-turn cap is 2000; choose a smaller explicit --max-turns for a bounded review. Correct a parser error before retrying; changing the prompt cannot repair an invalid option. Use agent-cli --version in bug reports and agent-cli --help (also -h) to compare your installed executable with this reference.

--managed-turn-file FILE supplies an internal managed-turn request; it is not a text prompt file. --managed-deny-mutations is an internal worker policy flag rather than a replacement for public --no-yolo automation. Do not construct internal requests by copying a transcript export.

Managed integration turn payload

--managed-turn-file FILE is an internal integration interface, not the ordinary text-file prompt option. The version-1 JSON object requires text. Omitted version defaults to 1; other versions are rejected. images and files default to empty arrays. Each media object requires path and mime, with optional name. Paths identify readable files in the launched process's filesystem, not remote URLs. Their bytes are loaded as attachments; the declared MIME type is supplied to the model.

{"version":1,"text":"Describe the attached screenshot without modifying anything.","images":[{"path":"/absolute/path/screenshot.png","mime":"image/png"}],"files":[]}

Optional bridge_directory is the integration's bridge path. Optional context requires string gateway and integer chat_id and user_id; integer message_thread_id and reply_to_message_id are optional. These describe integration context, not permission to impersonate a user. Producers must preserve the real authorized context. Keep request files and attachments private. A missing request file, malformed JSON or unsupported version fails loading; fix the producer payload instead of retrying a remote action blindly. Use --prompt-file for normal text-only automation.

Run a bounded one-shot task

agent-cli --cwd /absolute/path/to/project --no-yolo --no-computer-use \
  --max-turns 6 --save-session \
  -p 'Read the README and report the documented test command. Do not edit files.'

Replace the project path. -p runs one prompt and exits rather than opening the normal composer. --save-session retains the conversation for later inspection; without it, ordinary one-shot runs are not persisted as sessions. --no-yolo prevents a headless process from silently approving mutations. It may therefore prevent a requested build or test that writes files.

For a longer specification, use --prompt-file review-request.txt. Keep secrets out of both prompt files and shell arguments. --max-turns bounds model turns, not elapsed seconds or monetary cost. Inspect the final output: reaching a limit is not proof that the requested task completed.

Capture stdout and stderr separately: assistant text is streamed to stdout; activity, errors and resume hints can appear on stderr. The run command has no structured-output flag: do not parse this stream as the JSON returned by the administrative sessions commands. For retained structured inspection, save the session and use sessions show ID --json afterward.

A failed foreground one-shot turn exits unsuccessfully. A completed turn exits normally, but cancellation can also follow the normal quit path: exit status zero alone does not prove completion or successful tests. Have automation check the requested result and explicit test evidence as well as process status. Use an external timeout for a wall-clock limit, and treat interrupted output as incomplete. Before rerunning, inspect persisted history and external state; a retry is not an exactly-once transaction and may repeat effects already performed.

Manage local storage

These commands manage the local PostgreSQL cluster, not an external database. Use the packaged PostgreSQL 18 binaries, run as the owning user, and keep its state directory writable with sufficient free disk space. start initializes a missing cluster, starts a stopped cluster, ensures the database and applies migrations. migrate also starts storage if necessary; it is not a PostgreSQL major-version upgrade.

Interpret storage diagnostics

Successful start reports managed PostgreSQL is running and migrations are up to date; successful migrate reports managed PostgreSQL migrations are up to date. The default socket port number is 55432, but TCP listening is disabled. A normal unrelated TCP service on that port is therefore not the first explanation for failure. Check the actual Unix socket and server identity before stopping another process. The log is postgres.log beside the cluster's data and run directories.

Before migration and after failure

Arrange a maintenance window and stop agent clients that write to this store. Make a verified PostgreSQL backup and preserve the associated agent configuration and filesystem artifacts. A plain copy of a live data directory is not a reliable backup; use PostgreSQL-aware backup tooling or a confirmed stopped-cluster copy. Keep the original backup separate from the migration target.

Run agent-cli storage migrate, check its result, then run agent-cli storage doctor and inspect a known session. If migration fails, retain the exact error and postgres.log, fix the reported cause and retry only with the intended compatible build. There is no CLI rollback command. Do not edit migration bookkeeping or delete the cluster to silence an error. If recovery requires restoring, stop clients and the cluster, preserve the failed state for diagnosis and restore a verified compatible backup under the original owner before restarting.

Inspect sessions from scripts

agent-cli sessions list --json
agent-cli sessions show SESSION_ID --json --limit 50
agent-cli sessions show SESSION_ID --json --before TURN_INDEX --limit 50
agent-cli sessions wait SESSION_ID

Substitute an identifier from the list. sessions without a subcommand lists sessions in human-readable form. --json selects machine-readable output. For transcript pagination, --before requests older turns than the supplied cursor and --limit bounds turns, with a maximum of 500. Use returned cursor information rather than assuming a page is the complete transcript. wait waits for the session's lifetime lock to be released; it does not submit a new task or report model-task success. It exits silently once the lock is inactive. An invalid identifier or missing session directory fails; an unlocked existing directory returns immediately. This is useful for handoff, not as a task-result API.

agent-cli sessions import [--cwd DIR] reads the harness's transferred-session JSON format from standard input and prints the imported session identifier. It is not a general Markdown-file importer, and a transcript listing is not necessarily a transferable session document. Interactive /export produces a readable Markdown record instead.

Import a session transfer

agent-cli sessions import --cwd /absolute/project < transfer.json reads one raw transfer object from stdin and prints its imported session ID. The supported producer used by the product is remote /afk, which serializes the active session and pipes it into this command over SSH. Prefer that handoff for moving work; neither /export Markdown nor sessions show --json is this transfer representation.

This is a version-coupled runtime format, not a promise that arbitrary third-party chat JSON can be imported. Preserve canonical response items from the producer rather than fabricating them from visible assistant text. An import preserves the source ID; it fails instead of overwriting an existing session. --cwd overrides the stored directory, but does not copy that directory or credentials. Invalid JSON reports invalid transferred session; storage or duplicate-ID failures must be resolved before retrying. Inspect sessions show ID after success before resuming. Do not delete an existing conversation merely to bypass a collision.

JSON shapes and pagination

sessions list --json writes an array of summaries to stdout; warnings go to stderr. Summary fields are id, title, updatedAt, provider, model, effort, cwd, isRunning, isLocked, and isArchived. Running and locked are distinct observations, not proof that a task succeeded.

The list includes archived entries but excludes deleted sessions. It is not filtered to the current working directory. Ordering is newest updatedAt first, with session key as the tie-breaker. Corrupt or incompatible metadata produces stderr warnings and is omitted from the array; therefore an empty array plus warnings is not proof that storage contains no records. Apply your own explicit project/archive filter when scripting rather than taking the first entry as the current conversation.

sessions show ID --json without pagination returns meta and all turns. Each turn contains userText, assistantText, error, and toolEvents. This is a display-oriented transcript, not a complete provider request dump or the transfer format accepted by import.

1. Request sessions show ID --json --limit 50.
2. Read page.hasOlder. When true, find the smallest index in the returned turns.
3. Request sessions show ID --json --before INDEX --limit 50 with that index. The cursor is exclusive.
4. Continue until hasOlder is false, preserving turn indexes when assembling chronological output.

Paginated output adds each turn's index and a page object with generationStart, totalTurns, hasOlder, and hasNewer. Do not invent a nextCursor field. Pagination requires --json; --limit must be between 1 and 500; the cursor is a nonnegative integer. Supplying --before without a limit uses 50. An unknown session or storage failure is an error, not an empty successful transcript. Keep stderr separate from JSON and check process success before parsing output.

Manage MCP connections outside the TUI

OAuth scopes and logout identity

Repeat --scope SCOPE on agent-cli mcp login URL for step-up authorization. The requested set combines the selected challenge/resource/configuration scope set with previously granted scopes and the additional flags, without duplicates. Previous grants and client registration are reused only when issuer and resource match. offline_access is requested only when advertised by the authorization server. Login starts authorization; a scope flag does not itself grant access. Review consent and verify the intended account with a harmless read after reconnecting.

Credential files under ~/.haskell-agent/credentials/mcp/ are keyed from the exact endpoint string. Use the same URL spelling, including its query, for login and logout. agent-cli mcp logout URL removes that local credential file if present. It neither removes the configured server nor calls a provider revocation endpoint. A separately running process can retain in-memory credentials: disable/restart its MCP runtime to end that connection, and use the service's account controls if you need to revoke the grant remotely. Do not assume logout undoes prior tool effects.

Submit a server-provided prompt

/mcp prompt SERVER PROMPT_NAME topic=compatibility

Replace both names with a prompt actually advertised by your connected server. /mcps aliases /mcp. Arguments are string key/value tokens split at the first equals sign; a token without equals has an empty value. Follow the server's argument names and required fields; do not assume shell quoting or JSON objects are interpreted as typed arguments. A missing server or prompt error is displayed and returns to the prompt without starting a model turn.

A successful response is rendered and submitted as an expanded user turn to the current model, not merely inserted into an editable draft. Use only trusted server prompts and inspect the subsequent tool requests under the normal approval policy. The visible command label identifies the server and prompt; it is not a complete record of every argument or proof that the generated instructions are safe.

agent-cli mcp list --json writes a JSON array to stdout, with one object per configured server (including disabled entries). Fields are name, boolean enabled, transport, nullable url, command, string-array args, nullable cwd and string-array envKeys. Environment values are omitted. This is saved configuration, not a live connection-health probe. An empty catalog is []; malformed configuration is an error, not an empty successful catalog. Check process success before parsing and select by name, not array position. URLs and command arguments may still contain sensitive information, so inspect output before publishing it.

Use -- before a local server command when its arguments would otherwise be parsed as agent options. See MCP integrations for examples and how to refresh the runtime after changing configuration externally.

Gateway and worktree maintenance

agent-cli login opens provider credential management without starting a normal conversation. Inside the agent, /login (alias /accounts) opens account management. Follow authentication for account setup and credential-source details.

agent-cli gateway connect --url HTTPS_URL connects to a gateway; gateway status inspects it and gateway disconnect disconnects it. Changing gateway credentials changes the provider-routing trust boundary; do not assume an old conversation continues unchanged across that transition.

agent-cli worktree gc --dry-run --inactivity-days 30

This simulates managed-worktree adoption and collection eligibility, reporting reasons and estimated bytes without collecting. Review this report before deliberately running the same command without --dry-run. The inactivity argument must be a positive number of days. See worktrees before removing checkouts.

Without an explicit inactivity override, collection uses the configured policy (one day by default). Unmerged work does not expire merely because it is old. Enrollment is a deliberate change to retention behavior, not an inspection command.

Conversation and work

Sessions

Configuration and tools

Clipboard, attachments, and navigation

Provider and capability-specific commands

/fast applies to the Codex dialect. The Grok Build dialect exposes the following commands only when the corresponding tool is available:

/voice starts a voice call and requires ChatGPT sign-in. This is distinct from dictating a text prompt. /mcp prompt SERVER NAME [key=value…] runs an MCP server prompt. /codemod enables code mode for the current session. When a command is absent, check /help and /session-info rather than assuming every provider exposes the same capabilities.

Local command outcomes

/btw What does this error mean? makes a single side request using a snapshot of the current conversation. No client tools run; an attempted tool call is an error, not a background investigation. Its answer does not become a normal persisted main-conversation turn. It still makes a provider request and can incur usage. Cancellation, empty answers and provider failures are reported for the side question without turning it into a new main task.

/shell none removes shell tools from the active tool set; /shell both enables both GHCi and Bash. The other modes are ghci and bash; /shell alone reports the selection. Disabling GHCi suspends that runtime. This changes tool availability, not the safety policy, and is not a guarantee that every previously launched external Bash process has been terminated.

For quieter terminal output, launch agent-cli --motion reduced or agent-cli --motion off. Full mode animates indicators; reduced and off use static indicator frames and disable native progress animation. Reduced mode retains a faster refresh cadence than off. Neither disables task execution or hides task-state updates.

--prompt-file reads a text file using the process's text encoding and strips leading/trailing whitespace, just as a literal prompt is trimmed. Keep prompts in UTF-8 and use a UTF-8 locale. A missing, unreadable or undecodable file is an input error, not a fallback to an empty prompt. It cannot be combined with -p/--prompt or --managed-turn-file.

The automatic interface is fullscreen only when both stdin and stdout are terminals, the launch is not one-shot, and --minimal is absent. --fullscreen does not override the one-shot or terminal requirements. Use --minimal when integrating with terminal scrollback or a recorder.

/fast toggles the Codex request service tier between priority and the normal default. It requires both the appropriate command catalog and matching active-model metadata advertising that tier. Otherwise it reports that fast mode is unavailable. Priority service can have different provider pricing or usage treatment; it is not a free local speed setting. Toggle again to return to the default tier.

/codemod (alias /code-mode) saves/resumes the current persisted session through a runtime restart with code mode enabled. It is an enable command, not an on/off toggle or a global preference. Use --no-code-mode on a later launch to explicitly disable code mode. The restart keeps the session identity; availability still depends on the selected provider's supported tools.

Invalid arguments and commands unavailable in the active provider's command catalog are rejected with a command error; they are not silently submitted as a coding prompt. Use /help NAME and correct the syntax before retrying.

/view-plan (also /show-plan and /plan-view) displays the saved Markdown plan for the current session. If no nonempty plan exists it reports No saved plan is available for this session. Viewing a plan does not create or approve one.

/recap generates a catch-up summary, whereas /compact changes the working context to reduce its size. Requesting a recap is not a substitute for compaction and should not be expected to lower context usage.

/retry retries the retained failed turn rather than your current draft; with none retained it reports No failed turn is available to retry. Before retrying after an uncertain tool result, inspect the actual file or remote resource. A failed model turn does not mean earlier external effects were undone.

Initialize a guide and update the CLI

/init checks for AGENTS.md in the current directory. An existing entry is left unchanged. Otherwise it asks the model to generate a concise “Repository Guidelines” document covering repository structure, build/test commands, style, tests and contribution conventions. This is generated advice, not a fixed template or proof the commands work. Review the resulting diff and verify project commands before committing it.

/update-and-restart requires a persisted session. The current updater specifically removes the haskell-agent Nix profile entry, adds github:digitallyinduced/haskell-agent with flake configuration accepted, and executes agent-cli --resume SESSION_ID from PATH. It is not a generic updater for arbitrary package-manager or source installations. Note your session ID first and ensure Nix and the intended CLI are on PATH.

If updating throws an error, the running runtime reports update failed and attempts to resume with its existing implementation. Profile removal and installation are not atomic: a failed install can leave the profile entry absent. Repair installation before exiting that process. The newly executed command receives the resume ID, not every original transient launch flag; reapply required explicit overrides when launching manually.

Command aliases

Aliases use the same arguments and availability rules as their canonical command; they do not enable otherwise unavailable capabilities.

Recurring prompts are detached work

/loop 5m In /absolute/path/to/project, inspect the status of PR 123. Report a short status, make no changes, and stop this check.

This example requires the scheduler capability. Replace both the project and PR. The agent creates a schedule; each fire runs in a detached background subagent, not with the whole parent conversation. Include paths, identifiers, status commands, success conditions, and stop conditions in the stored prompt. A single fire should finish, not poll indefinitely.

Intervals use s, m, h, or d, with a minimum of 60 seconds. Without a cadence the agent should ask rather than assume one. Creation requests an immediate first fire. Check the confirmation for cadence, stop condition, seven-day expiry, and task_id. The parent/user owns cancellation: ask the parent to cancel that task by its identifier through the scheduler. A detached child cannot modify its schedule. Merely exiting a child or receiving one successful check is not cancellation.

Enable computer control for a session

/computer-use
/computer-use on
/computer-use off

The argument-free command reports the current setting. Before enabling it, confirm that the active provider and platform support computer use. An unavailable combination reports that limitation rather than making control available. Enabling changes the session's tool availability; it does not grant consent to control the desktop.

Changing this setting clears the remembered computer-tool approval. After enabling, expect a fresh approval before control. Disable it when finished, and check the reported state. Turning it off is not an undo operation for clicks, typed text, files or messages produced earlier. See approvals and sandboxing before using a desktop with sensitive windows or accounts open.

Goals, workflows, and research

/goal Investigate the failing parser test and fix only its cause.
/goal status
/goal pause
/goal resume
/goal clear

A goal tracks an objective and progress; it is not permission to ignore approval rules. Pause before changing direction, inspect status, and clear an obsolete goal. The optional positive integer --budget N is an advisory token budget, not an enforced spending cap or the CLI's model-turn limit. Goal state is held in memory, so check status rather than assuming a restart restores it. Request evidence for completion rather than treating a status label as a successful test.

Omitting the budget leaves it unset. Setting a new objective replaces the current goal and starts a fresh progress list. Pause accepts an active goal; resume accepts a user-paused or blocked goal, not a completed one. A missing goal or incompatible state produces an error without inventing a new objective. If blocked, resolve the reported cause before resuming. Completion ends goal mode; clear removes the objective, not work already performed. See goal lifecycle and tool updates.

/workflow runs
/workflow deep-research Compare the documented migration paths for our database.
/deep-research Compare the documented migration paths for our database.

/workflow NAME INPUT launches the named workflow with the input as its query; /deep-research is the deep-research workflow shortcut. Look for a real workflow-tool result and inspect /workflow runs. A prose answer alone is not evidence that a background workflow launched. If a workflow name or option is rejected, inspect the error rather than assuming the agent silently ran an equivalent procedure. Read the generated report and verify its citations before relying on it.

Workflow results and lifecycle

The supported named workflow is deep-research, with a nonempty research query. Slash-command text becomes the query, not a set of shell flags. See the workflow tool contract for structured input and validation-only calls; arbitrary scripts, agent budgets, and resume-from-run options are not supported.

A successful launch returns immediately with a tracked run and child agent. Completion is delivered through the subagent mechanism. The research report is the child agent's result, not a guaranteed file at a fixed path. Ask to save a reviewed report explicitly if you need a repository artifact. The research instruction requests primary sources, cross-checking, uncertainty and a concise cited report; it does not guarantee that every claim is correct.

/workflow runs lists the display name, wf_N run ID, objective, start time and child-derived status: pending, active, complete, failed, interrupted, closed or unknown. An empty list means no tracked runs in this runtime. Unknown means the child cannot be found, not that research completed. This in-memory run index is not a durable workflow scheduler or a resumable job queue across application restarts.

Workflow management operations such as cancel or resume return workflow_management_unsupported; they must not be treated as successful cancellation. To stop a running research child, request the ordinary agent interruption operation for that child and verify its resulting status. Interrupting a foreground response is not proof that a background child stopped. Neither interruption nor closing a child reverses tool effects already performed. Inspect a failed run's child output before launching another potentially duplicate investigation.