Get started · v0.2

Own your agent environment.

Install one local control plane, establish one Git-backed source of truth, then inspect and safely provision the tools on every machine.

01 / Install

Install agentctl

The installer supports macOS and Linux, requires Node.js 20 or newer, installs without sudo, and verifies the downloaded GitHub release archive checksum.

curl -fsSL https://agentctl.justrepl.com/install.sh | bash

Review the installer source before running it.

PATH recovery

If ~/.local/bin is not on PATH, the installer prints the exact export line. It does not edit shell startup files.

02 / Canonicalize

Initialize the canonical root

agentctl init
agentctl root

By default, init creates ~/.agentctl and initializes a Git repository on main when Git is available. It creates no commit, remote, account, or network request.

Use an explicit root or disable Git initialization when needed:

agentctl init ~/src/my-agent-environment
agentctl init --no-git
AGENTCTL_ROOT=~/src/my-agent-environment agentctl root

The command is idempotent for an already-valid canonical root and refuses an unrelated non-empty directory. Preview all scaffolded paths with agentctl init --dry-run --json.

Versioned: agentctl.yaml, catalog/tools.json, shared guidance, skills, and target intent.
Ignored: .agentctl/state/ machine observations and verified operation receipts.
External: Agent credentials, sessions, caches, and provider-owned configuration.

03 / Version

Push your environment to GitHub

Review the generated files first. Choose a private repository if your guidance or topology should not be public.

cd ~/.agentctl
git add .
git commit -m "Initialize canonical agent environment"
git remote add origin git@github.com:YOUR-USER/YOUR-AGENT-ENV.git
git push -u origin main

Never commit credentials

The scaffold excludes agentctl machine state, but you remain responsible for additions. Store secret references—not secret values—in canonical source.

04 / Observe

Know which agent tools are present

agentctl agents list
agentctl agents status
agentctl agents status claude --json

list reads the static catalog. status invokes only each selected tool's documented version query, with a timeout, then reports executable provenance, detected channel, desired state, and drift.

v0.2 supports OpenAI Codex CLI, Claude Code, OpenCode, Gemini CLI, GitHub Copilot CLI, OpenClaw, and Hermes Agent. Default and alternative npm, Homebrew, and official native channels are documented against their upstream sources in the complete lifecycle contract.

05 / Provision

Plan first. Confirm explicitly.

agentctl agents install codex --dry-run
agentctl agents install codex --yes
agentctl agents update codex --yes
agentctl agents uninstall codex --yes

Without --yes, a mutation command prints its exact plan and exits with status 2. --dry-run exits 0 and changes nothing. A confirmed operation verifies package-manager and runtime preconditions, executes a static recipe without shell interpolation, probes the result, and records success only after verification. Batches preflight every tool before the first mutation.

Select a supported channel

agentctl agents install claude --channel native --yes
agentctl agents install claude --channel npm --yes
agentctl agents install opencode --channel brew --yes

Existing npm, Homebrew, Claude native, OpenCode native, and Hermes native installations are inferred from a matching receipt or executable real path. A stale receipt cannot override the currently observed executable. Unknown uninstall ownership fails closed unless you name a channel; updates may use an upstream's documented self-updater.

Operate across the catalog

agentctl agents install --all --dry-run
agentctl agents update --all --dry-run

install --all installs missing catalog tools and updates/adopts already-installed tools so desired truth converges on the complete latest catalog. Bulk uninstall is intentionally unsupported. Remove one named tool at a time.

Configuration survives uninstall

agentctl removes the selected distribution, not your agent identity. Claude's ~/.claude is preserved; OpenCode native uses its keep-config and keep-data options; npm and Homebrew remove only their registered package.

OpenClaw and Hermes safeguards

OpenClaw update delegates to its supervised updater; uninstall removes the Gateway service before the npm package and retains ~/.openclaw. Hermes installs unprivileged with setup and browser bootstrap skipped, cannot edit shell profiles, retains its pre-update snapshot behavior, and preserves ~/.hermes on uninstall.

06 / Maintain

Update or uninstall agentctl itself

agentctl self update --dry-run
agentctl self update --yes
agentctl self uninstall --dry-run
agentctl self uninstall --yes

Self-update downloads the canonical HTTPS installer, validates its origin, records its SHA-256 as execution evidence, then lets the installer verify the versioned GitHub archive checksum before atomic activation. A minimum-version guard rejects downgrades, and the replacement version command must pass before success is reported.

Self-uninstall removes the managed command and version library. It rejects paths outside the selected home or any library path that could contain the canonical root. Your ~/.agentctl repository and all agent configuration survive.

07 / Audit

Inspect agent configuration without executing it

agentctl inspect
agentctl inspect --target codex
agentctl doctor

inspect reads known configuration roots, hashes SKILL.md definitions, inventories skill script directories, and inspects configuration key names. It does not execute any target CLI, plugin, hook, skill, script, or MCP server. doctor checks the local runtime and remains read-only.

Duplicate group: Two or more skills with the same SHA-256 digest for their SKILL.md content.
Divergent name: The same skill directory name resolves to different definitions across targets.
Potential secret field: A key resembles a credential field. Only key and line number enter the report; the value does not.
Script surface: A regular file exists under a skill's scripts/ directory. Presence is not proof it ran.

08 / Automate

Use versioned JSON contracts

agentctl inspect --json > environment.json
agentctl agents status --json > tools.json
agentctl agents install gemini --dry-run --json > plan.json

JSON output contains no ANSI formatting. Inspect, desired-tool, catalog, tool plan/receipt, and self plan/receipt schemas are published under spec/schemas.

agentctl inspect --strict --json exits 5 when potential secret-bearing fields are found. A mutation awaiting confirmation exits 2.

09 / Recover

Failure is visible, not ambiguous

Desired truth is written before an approved external lifecycle operation. If that operation fails, no success receipt is written; the next status report exposes desired-versus-observed drift. Fix the precondition and retry the operation.

Use the guarded self-uninstaller. The equivalent manual recovery is shown only for a broken CLI:

agentctl self uninstall --yes
# Manual fallback:
rm "$HOME/.local/bin/agentctl"
rm -r "$HOME/.local/share/agentctl"

This does not remove your canonical ~/.agentctl repository or any agent configuration.

Release boundary

What v0.2 does not claim

Filesystem presence does not prove a target loaded a resource.
Matching files do not prove equivalent behavior across models.
Tool installation does not authenticate the tool to its provider.
A recorded native-installer hash is evidence, not an independent signature.
agentctl does not yet import, render, reconcile, or roll back target configuration.

These are explicit roadmap capabilities. Follow development on GitHub.