CLI Reference

harbor — tool control plane for AI agents

usage: harbor <command> [args...]

setup:
  setup                  connect this agent to an operator
  setup status           check approval status / retrieve token
  whoami                 show agent identity and connection info
  agents                 list detected agents on this machine
  agents scaffold        create profiles for all detected agents

discovery:
  status                 show available plugins and lease status
  plugins                list all plugins
  plugins tools <slug>   show tools and parameters for a plugin
  skills                 list agent skills
  skills get <name>      print a skill to stdout
  skills get --all       print all skills

execution:
  p.<slug> <args...>     run a plugin
                         harbor p.modal volume list
                         harbor p.exa search --query "test"
                         harbor p.gh issue list

communication:
  request <plugin>       request access to a plugin
  msg "text"             send a message to your operator
  messages               show message history

runs:
  runs get <id>          show run details and events

system:
  doctor                 run diagnostic checks
  doctor --reset         kill daemon, wipe ~/.harbor, clean agent configs, upgrade
  update                 update harbor to the latest version

options:
  --json                 machine-readable JSON output
  --help                 show this help

Global flags

--profile <name> — target a specific profile. Harbor auto-detects the calling agent runtime (Claude Code → claude-code, Codex → codex, etc.) and uses that as the default. Global flags must come before the command name.

harbor --profile codex status
harbor --json whoami

--json — machine-readable JSON output. Supported by status, whoami, plugins, agents, skills, and doctor.

setup

harbor setup

Creates an agent identity and a claim for your operator to approve. Stores profile at ~/.harbor/profiles/<name>.json.

If already set up (daemon token present), prints status: ready immediately.

If a pending claim already exists, reminds you to share the URL instead of creating a new claim.

Also auto-scaffolds stub profiles for other agents detected on the machine.

harbor setup status

Polls the claim. When the operator has approved, retrieves and stores the daemon token. Returns status: ready on success.

Possible statuses: ready, pending, expired, approved_no_token.

Identity

harbor whoami

Shows profile name, daemon ID, paired operator email, and token expiry.

harbor agents

Lists AI agent runtimes detected on this machine. Detection covers: Claude Code, Codex, Cursor, pi, Amp, Gemini CLI, OpenClaw, Hermes, OpenCode, MastraCode, Mistral Vibe, GitHub Copilot.

harbor agents scaffold

Creates ~/.harbor/profiles/<family>.json for every detected agent that doesn't already have a profile.

Discovery

harbor status

The main status command. Shows profile info, paired operator, and all plugins grouped by status:

• ready — has an active lease, shows time remaining
• needs_lease / needs_setup — available, request access with harbor request
• missing_secrets — operator needs to add credentials in the dashboard
• mcp_disconnected — MCP connection lost

harbor plugins

Lists all plugins registered in the workspace. Shows slug, display name, and description.

harbor plugins tools <slug>

Shows the tools/operations for a specific plugin — method, path, parameters, types, defaults. Supports suffix matching (e.g. harbor plugins tools linear matches mcp.linear).

For CLI plugins, shows the binary name and whether it's installed locally.

Execution

harbor p.<slug> [args...]

Runs a plugin. The slug matches what harbor plugins lists.

harbor p.modal volume list
harbor p.exa search --query "latest AI news"
harbor p.gh issue list

If no args are passed, Harbor sends --help by default.

Communication

harbor request <plugin>

Requests access to a plugin. Sends a request message to the operator visible in the dashboard.

harbor request linear
harbor request modal --reason "need for batch jobs"
harbor request modal need for batch jobs

The reason can be passed with --reason or as trailing positional arguments.

harbor msg "text"

Sends a free-form message to the operator.

harbor messages

Shows the message history between this agent and the operator.

Runs

harbor runs get <id>

Shows details for a specific run. Prints the raw response from the Harbor API.

Skills

harbor skills

Lists embedded agent skills (name and description).

harbor skills get <name>

Prints a skill's content to stdout.

harbor skills get --all

Prints all skills, separated by ---.

System

harbor doctor

Runs five health checks:

1. profile — config file exists and loads
2. token — daemon token present and not expired
3. orbital — API server reachable
4. daemon — local daemon process running
5. plugins — at least one plugin ready

harbor doctor --reset

Kills the daemon, wipes ~/.harbor, cleans agent config directories, and optionally upgrades. Pass --no-upgrade to skip the upgrade step.

harbor update

Updates the harbor CLI to the latest version.

Config

Profiles are stored at ~/.harbor/profiles/<name>.json.

The Harbor API defaults to https://api.tryharbor.ai. Override with HARBOR_ORBITAL_URL or ORBITAL_URL. Config directory defaults to ~/.harbor; override with HARBOR_DIR or HARBOR_CONFIG_DIR (for profiles directory only).

To suppress auto-update checks, set HARBOR_NO_AUTO_UPDATE=1.