@amistio/cli

The Amistio CLI runner pairs a local repository with an Amistio project, syncs project-brain files, and runs approved work on the user's machine.

Install the stable runner:

npm install -g @amistio/cli
amistio

The package install provides the amistio command and the optional amistio-host-helper executable. The CLI is the local runner/harness worker; the web Runner panel is the primary UI for setup, provider auth, runner lifecycle, logs, and evidence. Repository cloning, project pairing, credential storage, sync watching, harness diagnostics, helper activation, and runner execution happen only when the user explicitly runs commands such as amistio bootstrap, amistio import, amistio pair, amistio sync watch, amistio harness status, amistio host-helper status, or amistio run --watch. When the app copies a personal project into an organization, the CLI command syntax stays the same; create the org-scoped code and run amistio import <code> from the intended local checkout. Import scans repo-local project-brain docs plus recognized repo-local IDE and agent instruction files such as Agent.md, AGENTS.md, claude.md, .claude/**/*.md, .github/copilot-instructions.md, .cursor/rules/*.mdc, .windsurfrules, and memories/*.md; these files are context inputs for the Amistio harness, not external execution routes. Durable Amistio memory belongs in docs/memory/, and global plugin memory outside the repository is not scanned by default.

For enterprise setup, use the web Runner panel as the primary guide. It shows repository, pairing code, GitHub access, AI provider, local runner, and verification readiness with plain next actions; advanced CLI logs remain secondary diagnostics. The panel also shows trust/privacy boundaries, cost forecast and budget posture, runner health, blockers, verification health, runner-version distribution, and structured Amistio harness event timelines from safe runner metadata.

Provider auth and runner setup should be web-led through typed runner commands. For example, the web can queue a provider auth command, the runner can perform the local provider/device-code flow, and the web can show the safe user code or verification URL without ever storing access tokens, refresh tokens, provider response bodies, or local auth file paths in the SaaS.

Runner execution profiles make runtime readiness explicit before local AI/tool execution. amistio run --watch --execution-profile hostWorktree keeps the default ADR-scoped Git worktree and checks Git, Node, Corepack, package manager, scripts, dependencies, and setup state. --execution-profile hostWorktreeWithSetup --setup-package-manager-install permits only the fixed package-manager install command inferred from package metadata, then rechecks readiness. --execution-profile dockerWorkspace validates Docker availability and a safe envelope mounted only to the worktree, rejecting privileged mode, host networking, extra mounts, and arbitrary environment injection; current runners still block approved work until containerized harness execution is enabled.

Optional host helpers are configured outside the SaaS with AMISTIO_HOST_HELPER_PATH. The official npm package ships amistio-host-helper for Level 1 supervised process execution diagnostics; enable it with AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper) on reviewed runner machines and confirm amistio host-helper status plus amistio host-helper conformance. PTY and sandbox requests use a helper only when its versioned handshake advertises support; otherwise the CLI returns deterministic unsupported results instead of silently downgrading. The npm helper does not advertise PTY or sandbox support. Helper request envelopes include allowlisted environment values, explicit sandbox policy metadata, and bounded normalized output, and must never include provider tokens, OAuth material, runner API tokens, local auth files, or arbitrary SaaS-originated shell text.

Before publishing the CLI, run the package release gate:

corepack pnpm --config.verify-deps-before-run=false --filter @amistio/cli release:check

The check packs and installs the package, rejects source maps/tests/source files in the tarball, verifies both installed bins, and runs helper handshake, status, and conformance from the installed artifact.

Native TUI package scripts exist as an auxiliary packaging spike, but current product focus is web-led runner commands and runner-owned harness execution.

Runner lifecycle controls in the web app, such as update, restart, and remove, apply only to the runner paired by that user unless the active organization role is an admin role. The runner API binds command polling, command status, logs, activity, and tool sessions to the local runner credential that produced them.

Runner Update installs the official @amistio/cli package and then refreshes the runner runtime. Once an update command is queued, watch mode finishes already claimed work and required finalization replay, then runs the update before claiming fresh work; parallel claim lanes stay out of fresh work while the command is active. Background runners attempt a replacement restart so the next heartbeat reports the new CLI version. If replacement restart metadata is missing or restart fails after a successful install, the old runner still stops and reports manual restart guidance instead of continuing to heartbeat the stale runtime. Foreground amistio run --watch sessions stop after a successful install with restart guidance; start the command again to load the updated package.

Current runners advertise the work kinds they can claim. Older runners that do not send this capability can continue legacy brain generation, implementation, and plan revision work, but they will skip source-aware assistant, impact-preview, semantic brain consolidation, project-context refresh, issue-diagnosis, app-evaluation, security-posture, Test-quality, implementation-Test-gate, implementation-verification, and prompt-batch work until updated. Normal runner polling also refreshes self-maintenance health in the Evaluate panel with bounded counts, trend, and safe record IDs for operational drift. The same polling path can run a throttled safe Project Brain consolidation pass that archives exact duplicate untouched generated review docs and queues semantic brain consolidation only when a compatible runner and active repository link exist. It also runs blocker elimination for failed/blocked work: autopilot-disabled projects get reviewable deduped unblock work, autopilot-enabled projects may requeue backend-proven safe rows or approve low-risk verification/handoff/stale-base repairs under policy, and true manual exceptions name the external input needed to resume. It does not upload source, full document bodies, secrets, commands, or local paths, and it does not delete brain records, repo files, approved/synced docs, or user-edited docs.

Prompt batches are first-class promptBatch work items for many approved prompts that should reach the worker together. The CLI claims one manifest, executes child prompts sequentially, reports per-child status back to Amistio, and stops according to the batch policy. This preserves auditability while avoiding repeated one-prompt handoffs; it is not shell-script batching, terminal loops, or hidden chat concatenation.

Tool session reuse is bounded. One-shot tool sessions close after successful completion, failed runs are blocked, active sessions are treated as already in use, and reusable sessions idle for more than six hours are closed before the next claim selects context. This keeps follow-up work from inheriting stale local AI context while preserving recent reusable sessions for related work.

Repository brain auto-sync is disabled until the repository link option is enabled in the app. After pairing, run amistio sync watch from the paired checkout to push recognized external brain Markdown/MDX files and explicit HTML artifacts under docs/html/<area>/, including local ADRs, plans, prompts, workflows, memory, context, architecture, and feature docs, to the app for review. Markdown is the default generation format; HTML appears only when a runner or user explicitly generated an HTML artifact. amistio run --watch also runs the same cycle between work polls when the option is enabled. The CLI skips templates, unsupported paths, oversized files, unchanged managed docs, and conflicts instead of silently overwriting web state.

Repository autonomy is disabled until the repository link option is enabled in the app. When enabled, Amistio can attach an audited low-risk autonomy-contract authorization to eligible runner work, including generated brain approval, impact preview, issue diagnosis, security posture scan, app evaluation cleanup, Test scans, implementation Test gates, low-risk implementation handoff, safe requeue, and implementation verification. The Runner panel shows and updates safe work scopes, allowed candidate types, max risk, optional runner binding, daily/concurrent/failure budgets, expiry/review/cooldown windows, and pause state. The CLI shows authorization id, candidate id/type, outcome, policy version, and work kind in amistio work list, claim logs, runner prompts, and milestone activity. Autonomy does not widen local runner permissions: pairing, supported work kinds, runner identity, Git worktree isolation, redaction, local-tool permission controls, and unsafe/review-required/blocked/repeated-blocker/paused/budget stops still apply. Organization workspace autonomy contracts can be changed only by org:admin members.

After pairing, confirm that the built-in Amistio direct agent capability is available:

amistio harness status
amistio harness providers
amistio harness tools
amistio tools
amistio host-helper status
amistio host-helper conformance

Configure a direct provider locally, then start the runner. For example, use GITHUB_MODELS_TOKEN or GITHUB_TOKEN for GitHub Models, or OPENAI_API_KEY for OpenAI:

amistio orchestrate "prepare the next implementation prompt" --provider github-models --model-id openai/gpt-4.1
amistio sync watch
amistio run --watch --provider github-models --model-id openai/gpt-4.1
amistio run --watch --provider openai --model-id gpt-4.1
amistio run --watch --execution-profile hostWorktree
amistio run --watch --execution-profile hostWorktreeWithSetup --setup-package-manager-install
amistio run --watch --execution-profile dockerWorkspace
amistio run --watch --provider github-models --model-id openai/gpt-4.1 --reasoning-effort high
amistio run --watch --provider openai --model-id gpt-4.1 --reasoning-effort high
amistio run --watch --max-concurrent-work 1 --provider github-models --model-id openai/gpt-4.1
amistio run --watch --background --provider github-models --model-id openai/gpt-4.1
AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper) amistio host-helper status
AMISTIO_HOST_HELPER_PATH=$(command -v amistio-host-helper) amistio host-helper conformance
amistio runner status
amistio runner repair
amistio runner smoke-session-lifecycle

Provider-backed model preferences use sanitized catalog fields: --provider, --model-id, optional --model-variant, and --reasoning-effort (auto, low, medium, high, or xhigh). Implemented direct providers include GitHub Models, OpenAI, Anthropic, Groq, OpenRouter, and local OpenAI-compatible endpoints; Gemini, Azure OpenAI, Bedrock, and Vertex AI are cataloged as planned direct providers. Provider credentials, API keys, and local secret paths stay on the runner; they are not stored in Amistio preferences or runner heartbeats.

amistio harness status, amistio harness providers, and amistio harness tools are local diagnostics for the built-in Amistio harness. They report the default harness boundary, safe direct-provider readiness, and bounded Amistio-owned tool adapters without uploading provider credentials, environment values, local config paths, or raw tool errors. Direct-agent runs also emit bounded harness events that the web Runner panel can show as model/tool/check/repair/finalization timelines instead of raw terminal or provider transcripts. The web Runner panel remains the primary setup flow.

External coding-agent harnesses and custom commands are not runner execution routes. Add new execution capability as typed Amistio-owned bounded tools instead of --tool, SDK, CLI, or --tool-command adapters.

amistio runner status reports local background runner state, latest heartbeat, and bounded resource usage when available. amistio runner repair rotates the local runner ID for the paired checkout after a forgotten-runner tombstone; use amistio runner repair --clear-credential only when you need to delete the local credential and re-pair from the Runner panel. Resource usage is latest-sample runner process memory/CPU plus safe aggregate system memory/load signals; it does not include source files, environment variables, command lines, process lists, credentials, or arbitrary local paths.

amistio runner smoke-session-lifecycle runs a local no-claim smoke for the runner tool-session lifecycle. It does not contact the API, claim production work, inspect source, or mutate local runner state; it verifies that completed one-shot sessions close and stale or active sessions are not reused by the direct agent.

The runner advertises its supported work kinds in heartbeats. Current runners can claim read-only projectContextRefresh jobs from the workspace Context panel and create due runner-driven refreshes when no fresh approved map exists. Context refreshes inspect the paired checkout locally without modifying files and submit only bounded summaries, slices, entities, relations, safe citations, confidence, freshness, and repo-relative paths. If a submitted context refresh contains unsafe evidence, unsafe paths, or a map too large to store safely, Amistio marks the refresh failed with a safe reason instead of storing the rejected raw result. Approved maps are reused as context packs for source-aware assistant and impact-preview work.

Current runners can also claim read-only issue diagnosis jobs from the web Issues panel, generate root-cause analysis and a proposed fix, and submit that result without modifying source. They can claim manual read-only appEvaluationScan jobs from the workspace Evaluate panel and create adaptive runner-driven evaluations during normal watch/background polling when app evaluation is enabled for the repository link; fresh clean evidence is skipped when there is no active app-evaluation finding to act on. Evaluation results contain bounded summaries, safe evidence, suggested actions, lifecycle proposals, and repo-relative paths only. Current runners can also claim manual read-only securityPostureScan jobs from the workspace Security panel and create due daily posture checks during normal watch/background polling. Security scan results contain bounded summaries, standard references, safe evidence, and repo-relative paths only.

App Evaluation scans do not run verification commands that would mutate the checkout. If whole-app verification would install dependencies, regenerate framework files, emit build artifacts, or otherwise create generated files, the runner reports stale or missing verification evidence and recommends a separate Test-gate or implementation verification run in a mutating worktree.

Current runners can claim manual read-only testQualityScan jobs from the workspace Test panel and create one due daily Test scan per repository when Test quality is enabled. Under a repository autonomy contract, testQualityScan and implementationTestGate are delegated evidence work instead of another approval interruption. Test scans run only existing lint, typecheck, test, coverage, build, or verify commands and submit bounded command summaries, coverage summaries, safe findings, blocked reasons, warnings, and repo-relative paths. Missing tests, missing coverage, low coverage, failing checks, flaky tests, and test gaps create autonomous repair work when delegated or reviewable plan-backed findings when not. Current runners also claim implementationTestGate jobs before implementation completion, PR handoff, or runner-managed push; a passing gate is required unless the web Test panel records an audited override. Blocked implementation Test gates submit structured Test findings, such as blockedEnvironment, with safe evidence, a suggested action, and a verification plan. Current runners can claim read-only implementationVerification jobs from Tasks to prove whether completed implementation work actually landed; verification submits bounded acceptance-criteria evidence, checks, gaps, outcome, and recommendation without mutating source. Source, secrets, environment variables, command lines, process lists, credentials, provider sessions, and arbitrary local paths stay local. Implementation or cleanup is queued separately only when a repository autonomy contract or explicit approval authorizes it.

When multiple approved items are eligible for the same compatible runner, server-side queue priority orders them before FIFO age. Completion-critical implementation Test gates remain first, followed by approved work that blocks the active objective or releases multiple blocked rows. Priority metadata is bounded and visible in Work rows, but it is not approval and cannot bypass runner capability, repository matching, claim lanes, worktree isolation, ownership, or non-delegable safety stops.

Runner-driven app evaluation, Test quality, and Security posture signals skip fresh clean evidence when no active finding, failed/blocked gate, or exception needs action. If an implementation Test gate fails or blocks under an enabled repository autonomy contract, Amistio queues one deduped low-risk test-repair implementation work item so the runner can continue from validation failure into repair instead of waiting for another approval. Project Home groups that work under persistent agent ownership with safe requester, runner, repository, existing-system reference, PR/no-op lineage, team ledger metrics, and human-interruption rate so enterprise teams can audit who did what without reading local agent logs.

Approved implementation work uses Git as the handoff boundary. During worktree preflight, the runner locally copies eligible ignored root dotenv files such as .env.local or .env.test.local from the paired checkout into the implementation worktree when the target is missing and ignored, so local tests can use the same machine configuration. Dotenv values, variable names, file contents, and local paths are not uploaded to Amistio, and copied dotenv files stay ignored so PR handoff does not commit them. Before local AI/tool execution starts, implementation work checks PR handoff readiness: GitHub remote support, default-branch fetch, Git commit identity, local gh authentication, and repository visibility. After the local tool completes successfully, the runner materializes approved Markdown, MDX, and HTML project-brain artifacts for the same work scope into the isolated worktree before final Git status, then classifies the final diff. Source-implementation work must include source, config, test, or other implementation-affecting changes before the runner opens or reuses a PR. If only project-brain or documentation artifacts changed, Amistio completes the work as no implementation produced instead of opening a misleading implementation PR. App-evaluation proof and lifecycle-cleanup actions are queued with explicit docs-only expected outcomes, so safe proof notes and plan metadata updates can create docs-only PRs without being mislabeled as source implementation. Other explicit docs-only work can also create docs-only PRs. No-change completion requires no source changes and no approved artifact changes, and runner-created no-change worktrees are removed after final clean checks. Prepare the runner machine with Git commit identity, fetch/push permission to the linked remote, and gh auth status. If artifact materialization, commit, fetch/rebase, push, or PR creation fails, the work item is blocked with safe recovery choices; source files and patches are not uploaded to Amistio. The Work panel can queue scoped Retry handoff or Retry cleanup commands only to the runner that owns the preserved worktree for the same work item, branch, and worktree key. Retry handoff can publish a clean preserved local-only implementation commit without rerunning the implementation prompt. Rebase conflicts capture bounded repo-relative conflict files and try git rebase --abort so the implementation branch can be retried or manually reviewed without leaving an active rebase. Dirty, unmerged, or ambiguous worktrees are preserved rather than discarded.

Runner-created implementation commits and new GitHub PR titles use Release Please-compatible Conventional Commit text. Existing open PRs for the same handoff branch are reused without title churn.

Failed or stale work can be requeued from the web Tasks panel. Requeue creates a new linked work attempt and preserves the original terminal attempt for audit history; Requeue safe sends one backend batch that recomputes safe candidates, reports already-active and skipped rows, and still uses linked attempts. Requeue is blocked while equivalent work is already active, when the paired runner does not advertise the needed work kind, or when the latest linked attempt repeats the same sanitized blocker fingerprint. Repeated runner setup, handoff, policy, verification, and worktree blockers require root-cause repair before another linked attempt. Completed implementation status is separate from proof: queue implementationVerification from Tasks when a plan needs source-aware evidence before cleanup or implementation status decisions.

Patch-context failures are typed recovery states. If a local tool reports a stale apply_patch context miss, such as an expected-lines mismatch, the runner marks the work with patch-drift recovery metadata and safe next actions instead of uploading raw patch output or leaving a generic failed row. Retryable API failures during implementation finalization are staged in the user-level Amistio finalization outbox and replayed before the runner claims more work, so a transient 500 does not require rerunning the local AI tool. Throttled 429 replay attempts honor API Retry-After metadata when present, persist a bounded local cooldown, and skip the not-yet-due entry while other eligible finalizations can continue. Accepted read-only runner results keep milestone and heartbeat side effects best-effort after the primary result submission succeeds, so a telemetry 500 does not turn a durable app-evaluation or similar result into failed work. Retryable watch-mode pre-claim heartbeat failures are also advisory and do not abort parallel polling; forgotten-runner, authorization, pairing, validation, and ownership failures still use the strict recovery path. When completion queues a required implementation Test gate, the source-work finalization remains pending locally, compatible runners claim the gate before unrelated implementation work, and finalization replays after the gate passes. If finalization replay finds that the stored work claim belongs to a forgotten, missing, stale, offline, or lease-expired runner, the CLI requests abandoned-claim recovery with the active runner's lane capacity and retries only after the server safely adopts the claim. Large abandoned-claim finalization backlogs are budgeted per watch poll, summarized separately from cooldown and gate deferrals, and left for later polls once the runner has made bounded replay progress so fresh claim lanes still get a turn. Adopted finalization claims use a short replay lease rather than a normal long-running work lease.

Runner setup and local-tool execution use bounded failure controls. During Git worktree preflight, amistio run --watch repairs safe stale Git registrations when the target worktree directory is missing and Git marks the registration prunable; dirty, present, or ambiguous worktrees are preserved. Other Git worktree preflight failures are retried by releasing the claim for another attempt, then fail the work item after --max-preflight-attempts attempts, defaulting to 3. Active local-tool runs renew the work lease, and --tool-timeout-seconds caps tool execution, defaulting to 1800 seconds.

The environment doctor blocks work before local AI/tool execution when git, node, Corepack, the package manager, required package scripts, dependencies, setup allowlist, Docker, or the requested execution profile is not ready. Foreground, background, and startup-service runners accept --execution-profile; use --setup-package-manager-install with hostWorktreeWithSetup when the runner may run the fixed package-manager install step in the execution worktree. Work and Runner surfaces receive sanitized profile/readiness metadata only; raw host paths, command lines, environment values, and secrets are not uploaded. Watch mode also performs a Git PATH preflight before auto-sync or work claiming. If the runner reports that Git is not available to the runner PATH, install Git or restart the foreground, background, or startup-service runner from an environment where git --version works. On macOS, service and GUI-launched runner environments may not inherit the same PATH as an interactive shell, so restart or reinstall the service after changing PATH.

Runner watch mode defaults to 5 bounded parallel claim lanes, and --max-concurrent-work <count> can explicitly set the advertised lane count up to the supported cap of 100. Use --max-concurrent-work 1 only when you intentionally want serial execution. The server enforces one active lease per runner lane, honors the advertised capacity, and keeps equivalent implementation scopes serialized through Git worktree locks; use separate lanes for independent work, not multiple attempts at the same ADR scope. Before local tool execution, the runner records a bounded user-level active claim with work item, lane, lease, implementation scope, and worktree key, then releases it on completion or failure; if another local lane already owns the same work or worktree, the runner skips execution and releases the server claim when possible. Dead local runner processes are pruned from this user-level ledger before same-worktree or same-work-item conflicts block a replacement lane.

Current runners recover abandoned server claims without impersonating the old owner. If a work item is still claimed by a forgotten, missing, offline, stale, or lease-expired runner, a compatible runner asks the API to release or adopt that claim through an audited recovery path before normal claiming or pending finalization replay continues. Pending finalization replay uses the active runner's lane capacity for adoption and retries only after the server returns ownership to that runner and lane. From the web Runner panel, forgetting an offline/stale runner marks it removed, cancels active commands, and releases its non-terminal claimed work for normal compatible-runner claim selection. Fresh live claims still reject non-owner renewals, releases, and finalization attempts. If a project has no compatible runner, work waits for setup until one is paired and heartbeating.

Watch mode prints a completed-work success once per work item, keeps fresh completion visible briefly, and returns old completed work to the ready state when no queued, running, blocked, failed, review, or runner-readiness action needs attention. Unchanged idle-ready status is printed once and then stays quiet until the next action changes.

If no work is claimed but a retryable project-status read fails, watch mode prints Status unavailable and retries on the next poll. This status is about the idle next-action summary, not the claimed work or finalization path.

Known validation failures such as unsafe_context_path are printed with attention-needed next steps. For project-context refresh path-safety failures, deploy the latest web/API fix, update and restart the runner when applicable, retry the refresh, and capture only bounded non-secret output if it repeats.

If watch mode reports that the runner was forgotten by the server, run amistio runner repair from the paired checkout, then start amistio run --watch again. The repair command stores a fresh local runner ID because the default ID for a machine/project/repository is stable and can remain tombstoned. Use --clear-credential only when the Runner panel tells you to create a fresh pairing code.

App-evaluation and impact-preview result finalization rejections print safe validation paths and preserve the local finalization evidence without exposing raw source or secrets. If a structured app-evaluation or impact-preview result is rejected, update and restart the runner, confirm the web/API deployment is current, and retry before acting on cleanup, implementation, or risk recommendations. Accepted impact-preview results that cannot be stored safely are marked failed with a bounded reason instead of uploading raw source or secrets.

When a newer manual or adaptive app evaluation is queued for the same repository, Amistio marks older queued or running app-evaluation scans stale and closes their scan work without deleting historical scans, findings, or generated plans. Runner-driven evaluation skips fresh clean evidence instead of spending another hourly scan when there is no active app-evaluation finding to act on.

When brain generation or plan revision output is parsed but the Amistio API is temporarily unavailable during finalization, the runner keeps a safe pending result envelope in user-level Amistio config and replays it before claiming more work. The envelope uses a stable idempotency key and does not store raw tool stdout, provider sessions, credentials, or arbitrary local paths.

For headless startup after login on supported user-level service managers:

amistio runner service install --provider github-models --model-id openai/gpt-4.1 --reasoning-effort high
amistio runner service install --provider openai --model-id gpt-4.1 --reasoning-effort high
amistio runner service status
amistio runner service remove