CLI reference

Every command Agent Guard exposes, with the flags that matter and what they do. This page is a lookup table. For walkthroughs that show these commands in context, see the rest of the docs.

Command summary

agentguard run <agent> [flags]              Run an agent under Agent Guard
agentguard fetch <agent> [flags]            Pre-download the agent binary to the local cache
agentguard register [flags]                 Authenticate and register with the configured hub
agentguard policy add <ref> [flags]         Add a policy source (global or workspace-scoped)
agentguard policy remove <ref> [flags]      Remove a policy source
agentguard policy list [flags]              List configured policy sources
agentguard sync                             Force a policy sync without running an agent
agentguard env list [flags]                 List named environments
agentguard env info <name>                  Show environment details and disk usage
agentguard env rename <old> <new>           Rename an environment
agentguard env fork <source> --name <new>   Clone an environment (APFS copy-on-write)
agentguard env delete <name>                Delete an environment
agentguard trusted-keys add <key>           Add a cosign public key to the trusted set
agentguard trusted-keys list                List trusted keys
agentguard trusted-keys remove <key-id>     Remove a trusted key
agentguard status                           Show active policies and protection status
agentguard top                              Live view of running microVM resource usage
agentguard logs [flags]                     Tail audit and server logs together
agentguard uninstall [flags]                Remove Agent Guard from the machine
agentguard --version                        Print the installed version
agentguard --help                           Show help for any command or subcommand

agentguard run

Launches an agent inside Agent Guard's enforcement environment.

agentguard run <agent> [flags]

<agent> is one of claude-code, gemini, codex, or openclaw.

Flag	Default	What it does
--workspace <path>	none	Directory the agent can read and write. Required for any non-trivial use.
--env <name>	auto-generated	Named environment to use. Omitting auto-generates <agent>-<sha256(workspace)[:12]>.
--agent-ref <ref>	none	Pull and apply an agent definition from an OCI registry. See Run with an agent definition.
--policy-ref <ref>	none	Pull a policy ref for this run, scoped to the workspace.
--pass-env <KEY>	none	Pass a host environment variable into the microVM. Repeatable.
--pass-cloud-creds <provider>	none	Pass cloud provider credentials. Valid: aws, gcp, azure, vault, kubernetes, all. Repeatable, comma-separated.
--no-sync	false	Skip the automatic policy sync for this run.
--no-live-sync	false	Use vsock tar transfer for the workspace instead of virtiofs live mount.
--no-workspace	false	Run without a workspace mount. Uses the default environment.
--shell	false	Drop into a shell inside the microVM instead of starting the agent.
--version <ver>	pinned	Override the agent version (Claude Code only today).
--ram <MiB>	3072	Memory allocated to the microVM.
--vcpus <N>	4	Number of virtual CPUs allocated to the microVM.
--yes	false	Skip confirmation prompts (protection downgrade warnings, first-run consent).
--plain-http	false	Allow insecure HTTP registry connections.

Examples:

# Default run
agentguard run claude-code --workspace ~/projects/myapp

# Pass GitHub token and AWS credentials
export GH_TOKEN=$(gh auth token)
agentguard run claude-code \
  --pass-env GH_TOKEN \
  --pass-cloud-creds aws \
  --workspace ~/projects/myapp

# Pull a specific agent definition from Hub
agentguard run claude-code --agent-ref jozu.ml/acme/my-agent:v1 --workspace ~/projects/myapp

# Debug a microVM problem with a shell
agentguard run claude-code --shell --workspace ~/projects/myapp

agentguard fetch

Pre-downloads the Linux ARM64 agent binary to the local cache without starting a microVM. Useful for CI pipelines, air-gapped environments, or any situation where you want the download to happen ahead of the first agentguard run.

agentguard fetch <agent> [flags]

<agent> is one of claude-code, gemini, codex, or openclaw.

Flag	Default	What it does
--version <ver>	auto-detected	Version to fetch. If omitted, Agent Guard detects the version from the host binary.

Examples:

# Download the default claude-code version
agentguard fetch claude-code

# Download a specific version
agentguard fetch claude-code --version 1.0.25

The binary is cached at ~/.agentguard/vm/<agent>-<version> (for example claude-code-1.0.25). Subsequent agentguard run invocations use the cached file and skip the download.

agentguard register

Authenticates this Agent Guard installation and registers it with the configured Jozu Hub. Registration is required to use Hub-backed features: centralized policy distribution, fleet visibility, and audit log sync.

agentguard register [flags]

The command runs the OAuth device-authorization flow: it prints a URL (and opens it in your browser unless --no-browser is set), waits for approval, then saves the resulting tokens to ~/.agentguard/session.json and registers the machine's public key with the Hub.

Flag	Default	What it does
--force	false	Rotate the keypair and re-register, replacing the existing identity. Use when moving a machine to a new Hub or recovering from a corrupt identity.
--device-name <name>	hostname	Override the device name shown in the Hub fleet view. Defaults to os.Hostname().
--no-browser	false	Print the verification URL without attempting to open it. Use on headless machines.
--token <token>	none	Replay a device-flow access token instead of running the interactive flow. Intended for CI; mutually exclusive with --token-stdin.
--token-stdin	false	Read the device-flow access token from stdin to avoid shell history exposure. Mutually exclusive with --token.

If Agent Guard is already registered and the session is valid, register exits immediately. Pass --force to rotate credentials.

agentguard policy

Manages policy sources. See Manage policies for the full flow.

agentguard policy add

agentguard policy add <ref> [flags]

Flag	What it does
-w, --workspace <path>	Scope the policy to a workspace path. Use -w . for the current directory. Omitting adds to global scope.
--registry <host>	Override the registry host. Saved to config.json for future syncs.
-u, --username <user>	Registry username. Stored in macOS Keychain.
-p, --password <token>	Registry password or token. Stored in macOS Keychain.
--pub-key <path>	Verify the policy artifact signature against this cosign public key.
--plain-http	Allow insecure HTTP registry connections.

agentguard policy remove

agentguard policy remove <ref> [flags]
agentguard policy remove --all [flags]

Flag	What it does
-w, --workspace <path>	Remove from a specific workspace scope. Omitting removes from global.
--all	Remove every source at the specified scope.

agentguard policy list

agentguard policy list [flags]

Flag	What it does
-w, --workspace <path>	Show global sources plus the sources scoped to this workspace. Omitting shows everything.

agentguard sync

Forces a sync of every configured policy source without running an agent.

agentguard sync

Useful for verifying that a new policy version is reachable before the next agent run, and for refreshing policies on machines that have not run the agent recently.

agentguard env

Manages named environments. Each named environment is an overlay (root, usr-local, opt, home) that persists installed packages, auth tokens, and tool config across runs.

agentguard env list                          # All environments
agentguard env list --agent claude           # Filter by agent
agentguard env info <name>                   # Show details + disk usage
agentguard env rename <old> <new>            # Rename
agentguard env fork <source> --name <new>    # APFS copy-on-write clone
agentguard env delete <name>                 # Delete

env fork uses APFS copy-on-write so cloning is near-instant and disk-cheap until the new environment diverges from the source.

agentguard trusted-keys

Manages the cosign public keys Agent Guard trusts for policy signature verification.

agentguard trusted-keys add <path-to-pub-key>
agentguard trusted-keys list
agentguard trusted-keys remove <key-id>

When trusted keys are configured, every remote policy source is verified against the trusted set on sync. Signature mismatches block the pull and the previously cached version stays in place.

agentguard status

Shows the current state of Agent Guard on the machine: active policy sources, agent protection state, the configured Hub if any, and the install version.

agentguard status

Run this first when something is not working as expected.

agentguard top

Live view of microVM resource usage for any currently running sessions. Refreshes every two seconds.

agentguard top

Columns include PID, environment name, RAM usage, CPU usage, and uptime. Quit with q or Ctrl-C.

agentguard logs

Tails the policy audit log, policy server log, and microVM serial console together, formatted for terminal reading.

agentguard logs [flags]

Flag	Default	What it does
-n, --lines <N>	20	Number of recent lines to show from the policy server log before following.
--no-serial	false	Hide microVM serial console output (kernel dmesg and in-guest init).
-p, --previous <N>	0 (current)	Print the Nth previous serial log and exit rather than following. Useful for reviewing a completed session: -p 1 prints the last session's serial output.
--guardrails	false	Show only GuardrailPolicy decisions from the audit log, filtering out tool-call events.

For programmatic access to the raw JSONL audit log, use tail -f against the file directly. See Read logs and audit trails.

agentguard uninstall

Removes Agent Guard from the machine.

agentguard uninstall [--keep-config]

Flag	What it does
--keep-config	Preserve ~/.agentguard/config.json and policy sources. Useful when reinstalling.

The audit log under ~/Library/Logs/AgentGuard/ is preserved regardless of flags. See Uninstall and clean up for what gets removed and what stays.

Global flags

These work on any command.

Flag	What it does
--help, -h	Show help for the command.
--version	Print the installed Agent Guard version and exit.

Environment variables

Variable	Default	What it does
AGENTGUARD_HOME	~/.agentguard	State directory. Override for CI machines, shared dev servers, or non-standard home directories.
AGENTGUARD_NO_SYNC	unset	When set to 1, disables auto-sync on every run. Equivalent to passing --no-sync every time.
ANTHROPIC_API_KEY	unset	Used as the Claude Code credential when no OAuth token is cached.
GEMINI_API_KEY	unset	Used as the Gemini CLI credential when no OAuth token is cached.
OPENAI_API_KEY	unset	Used as the Codex CLI credential when no OAuth token is cached.