officectl CLI

officectl ships in the @agent-office/platform npm package (Node 22.18 or later), together with the server binary agent-office-server. Install it with npm i -g @agent-office/platform (the package comes from the vendor's npm registry: @agent-office:registry=<url> in .npmrc). Run it on the office host; officectl <command> --help shows each command's options.

Common options#

Commands that read the state directory (secrets, status, backup, …) must run as a user who can read it, normally the office user (sudo -u office officectl …).

officectl init#

officectl init [--answers file.yaml] [--dir path] [--forge-url url --forge-token-file file --org name ...]

Without --answers (and on a terminal), init asks: office name, office id, public URL, time zone, owner's name and email, forge URL, forge organisation, owner's forge username, state directory, agent home directory and default model; then the forge admin token and a model credential (input hidden). Flags pre-fill answers:

init is safe to re-run. With --dir <office repo> it reads the answers already in that repo's office.yaml, so a second pass (for example after installing the bundled forge) needs no flags. It does, in order:

1. Office repo directory: package.json (pinning @agent-office/platform), office.yaml, .npmrc, README.md, plugins/, deploy/. Existing files that differ are kept unless --force.
2. State directory (mode 0700) and secret store: the forge admin token, the model credential if given, and generated session.secret and webhook.secret.
3. Database and ledger genesis (office.initialized).
4. Forge bootstrap: the org; the teams approvers (write, merges) and agents (read); the repos <id>-policy, <id>-handbook, vault-template (a template repo) and <id>-office, seeded from the platform's templates; branch protection on main of the policy repo (merge: approvers; direct push: the office's admin account only, for ledger anchors), and of the office and handbook repos (pull requests only); the owner's forge user (--owner-forge-user) added to approvers, and on Gitea created first if it doesn't exist yet, with a temporary password printed once in the summary (change it after signing in to Gitea); a push webhook from the policy repo to <office.url>/api/webhooks/forge. Ledger forge.bootstrapped.
5. Owner account and a one-time sign-in link (valid 72 hours; re-running init reuses a live one).
6. Three hire pull requests on the policy repo for the founding agents: Chief of Staff (cos), Office Engineer (office-engineer) and Agent Resources (agent-resources). Merging a PR is the approval.

It ends with a summary (repos, sign-in link, hire PRs, model credential), the model-credential note, and numbered next steps. See Quickstart.

officectl install#

sudo officectl install [--with-forge] [--user office] [--domain host] [--port 8080] [--dry-run] [--platform linux|darwin]

Run it after init and npm install in the office repo. It executes a plan of files and commands; --dry-run prints the plan without doing anything.

On Linux it sets up:

• the root-owned account helper /usr/local/libexec/agent-office/agent-account, the only root command the office may run (create, lock, unlock and check ag-<slug> users);
• the sudoers file /etc/sudoers.d/agent-office (checked with visudo): the office user may run commands only as members of the agents group (never root or itself), with a cleared environment, plus the helper;
• Claude Code managed settings, /etc/claude-code/managed-settings.json (see the floor);
• on Ubuntu 23.10 and later, an AppArmor profile /etc/apparmor.d/bwrap so bubblewrap (the sandbox) may use user namespaces;
• the agents group, the office service user, the state directory (0700, owned by the office user) and the agents' home parent;
• a systemd unit agent-office.service (enabled, not started) and a Caddy site (/etc/caddy/sites/<id>.caddy, imported from /etc/caddy/Caddyfile; Caddy itself is not installed). Copies go to deploy/ in the office repo for review.

With --with-forge on Linux, it also downloads Gitea (sha256-checked), creates the git user, writes /etc/gitea/app.ini (mode 0640, owned by git:git, and only if it doesn't exist yet: Gitea writes its generated secrets back into it on first start, and a re-run must not rotate them) and the systemd unit, starts Gitea, creates a Gitea admin with a random password, stores an admin token as forge.admin_token, and adds a Caddy site for git.<domain>.

On macOS it writes the helper, sudoers file and managed settings (/Library/Application Support/ClaudeCode/managed-settings.json), creates the agents group and state directory, installs a launchd daemon, and writes a Caddyfile to deploy/. See Run on macOS.

Before the next steps it checks, as root, that the office user can run officectl at all: sudo -u <user> <node> <cli> --version for the global install ($(npm root -g)/@agent-office) and for the office repo's copy in node_modules. If not (typically a global install made under a strict umask, leaving @agent-office mode 0700), it prints the exact fix, sudo chmod -R a+rX "<dir>", and exits 1; re-run install after the fix. When Node or the npm root sits in a private home (/root/.nvm, …) it says so: chmod alone can't help there. If the office user doesn't exist yet (macOS, before you create it), it says how to check by hand.

It ends with numbered next steps; the step to store a model credential (officectl secrets set …) appears only when none is stored yet. Then start the office: systemctl start agent-office (Linux).

officectl doctor#

officectl doctor [--json] [--user office]

Checks, and for each failure prints what is missing and how to fix it. Exits non-zero if any check fails.

• Node version (22.18 or later) and that office.yaml is valid
• the claude CLI on the PATH, and on Linux with host.os_users on, that it also runs as an agent OS user (check claude.agents, run as the first member of the agents group once one exists; the fix is chmod -R a+rX "$(npm root -g)" or reinstalling under umask 022)
• sandbox: bwrap and socat on Linux, the AppArmor profile where AppArmor restricts user namespaces, sandbox-exec on macOS; warnings if host.sandbox or host.os_users is off
• the state directory: exists, mode 0700, owned by the office user
• the secret store: readable, with session.secret, webhook.secret and the forge admin token
• the model credential: API key or Subscription — personal use, or a failure with the model-credential note
• the database and ledger chain
• the sudoers file, the root-owned account helper, the agents group, and the managed settings protecting the state directory
• the forge: reachable, the admin token valid and a site admin, the policy repo present, the policy webhook active (it sends a test delivery)
• separation of duties (forge.separation): the office admin is not in the approvers team, and policy main takes no direct pushes (except ledger/anchors.jsonl), has a merge whitelist without the admin, and does not let admins force-merge. The fix is to restart the office server, which re-applies the protection
• the office server answering at <office.url>/healthz (a warning, not a failure)
• only when run as root: that the office user can run officectl (cli.office_user for the global install, cli.office_user.repo for the office repo's copy), by running sudo -u <user> <node> <cli> --version. Run as the office user, doctor can't check this (with a private global install it wouldn't start), so run sudo officectl doctor once after installing or upgrading. The fix it prints is sudo chmod -R a+rX "<dir>"

officectl verify#

officectl verify [--live] [--agent slug] [--other slug] [--json]

Runs the red-team conformance suite: each check attacks the office the way a compromised agent would, and passes only when the attempt is blocked. Each attempt is ledgered as verify.attempt. Needs at least one provisioned agent (two for the cross-agent checks).

Without --live, checks 7 and 9 are skipped. On a real Ubuntu 24.04 server, officectl verify --live passed checks 1 to 7 (check 9 has not yet been run on a real host). See Running the verify suite.

officectl smoke#

officectl smoke [--agent slug] [--colleague slug] [--timeout 300] [--url http://127.0.0.1:8080] [--as email] [--yes] [--json]

Post-install / post-upgrade check: starts a few real runs on the host against the running office, with the office's real model credential, and checks they work end to end. The office server executes them, so it must be running. It says how many runs it will start and asks first, because they cost a few cents; --yes skips the question, and without a terminal it won't start without it. Ledgered as smoke.started and smoke.finished.

Prints a table, every run with its cost and link, and an overall line. Exit code 0 when everything that ran passed (skips allowed), 1 on any failure, 2 on a usage error. See Smoke test.

officectl secrets#

officectl secrets set <name>     # value from a hidden prompt, or stdin when piped
officectl secrets list [--json]  # names only

Secrets live encrypted in the state directory: secrets.json.enc (AES-256-GCM) with its key in secrets.key, both mode 0600. list never prints values, and values never go in office.yaml, argv or logs. Setting a secret is ledgered as secret.created or secret.updated (the name only).

$ printf '%s' "$ANTHROPIC_API_KEY" | officectl secrets set models.anthropic_key

Secret names the office uses:

officectl connections#

officectl connections list [--json]                       # which connection credentials are stored (names only)
officectl connections secret <name> [--agent <slug>] [--key token] [--expires YYYY-MM-DD]

Stores a token for a connection from a hidden prompt or stdin, for the office account or (with --agent) one agent's own account. --key names an env secret of a stdio connection (default token). The office uses it from its next connection to the service, within five minutes. OAuth sign-in happens on the Connections page. Ledgered as connection.credential.set (never the value).

$ printf '%s' "$GITHUB_TOKEN" | officectl connections secret github --agent ada --expires 2027-01-31

--key webhook_secret (no --agent) stores a connection's inbound webhook secret, for example the signing secret Linear shows. Secrets: connection.<name>.token for the office account, connection.<name>.agent.<slug>.token for an agent's own; OAuth sign-ins keep ….oauth_client and ….oauth_tokens.

officectl browser#

officectl browser status [--json]                       # is there a browser; per agent: cookie count, stored sign-in hosts
officectl browser install                               # download Playwright's headless Chromium into <state>/browsers
officectl browser cookies <agent> <file|-> --site <host> [--site <host>]   # sign an agent in by importing cookies
officectl browser login <agent> <host>                  # store a username and password (hidden prompt, or two lines on stdin)
officectl browser forget <agent> [--site <host>]        # drop cookies and sign-ins (or one host's sign-in)

The office's browser for agents. Run as the office user. Cookies are kept only for the --site hosts and stored encrypted per agent; sign-ins go to the secret store as browser.<agent>.login.<host>.username|password. Ledgered as browser.storage.imported, browser.login.set and browser.storage.cleared (never values).

officectl github#

officectl github link <agent> [--connection <name>] [--expires YYYY-MM-DD] [--json]

Gives an agent its GitHub machine account for project repositories (Agents on GitHub). It prints the steps (create the account, add it as a collaborator on the granted repositories, create a fine-grained token scoped to them), then reads the token from a hidden prompt or stdin and checks it with GitHub: the login, Write access on each granted repository, and the expiry (from GitHub, else --expires). A token GitHub refuses is not stored. If the connection has no webhook secret yet, it creates one and prints it once, with the webhook URL.

--connection picks the GitHub connection when the policy has several (default: the only one). The agent must already be granted it, with its repositories. Stored as connection.<name>.agent.<slug>.token (+ .token_expires, .login); ledgered as connection.credential.set, never the token.

$ printf '%s' "$ADA_GITHUB_TOKEN" | officectl github link ada --json
{ "connection": "github", "agent": "ada", "login": "ada-acme", "expires_at": "2027-01-25T00:00:00.000Z", "repos": [{ "repo": "acme/website", "access": "write" }], … }

officectl backup#

officectl backup <file.tgz> [--with-forge]
officectl backup --remote [--with-forge]
officectl backup list --remote [--json]

Writes a .tgz (mode 0600) with a consistent online copy of the database (office.db, safe while the server runs), the encrypted secret store (secrets.json.enc) without its key, office.yaml, and a manifest.json listing each file's sha256, the platform version, schema version, ledger head and the sha256 of the key the secret store needs. Keep a copy of secrets.key apart from the backups: restore asks for it with --key-file (see Keep the key apart). Forge content (repos, vaults, mail) is not included unless you pass --with-forge; scheduled backups include it when the bundled Gitea is local.

--with-forge (Linux, bundled Gitea, run as root) also takes a cold copy of the forge: it stops Gitea for a few seconds, archives /var/lib/gitea (repositories, Gitea's database, LFS, packages) and /etc/gitea/app.ini into <file>.forge.tgz (mode 0600), and starts Gitea again. The manifest records that archive's name, size and sha256. With your own Gitea, back it up with its own tooling. See Backup & restore.

--remote (needs backup.remote in office.yaml) makes a backup now in backup.dir, named like scheduled ones (backup-<YYYYMMDD-HHMM>.tgz), encrypts it and uploads it to <prefix>/<office.id>/<file>.enc in the bucket, prunes the bucket to backup.remote.keep copies, and records backup.uploaded or backup.upload_failed. It exits 1 when the upload fails (the local backup is kept). backup list --remote lists the copies in the bucket, newest first: name, size, upload time, forge archive, object key. Both read the bucket credentials from the secret store (backup.remote.access_key / secret_key), or from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY when both are set. See Off the machine.

officectl restore#

officectl restore <file.tgz> [--key-file secrets.key] [--dir path] [--state dir] [--force] [--with-forge]
officectl restore --from-remote <latest|backup-YYYYMMDD-HHMM|object key> [--key-file secrets.key] [--passphrase-file file] [--dir path] [--state dir] [--force] [--with-forge]

Checks the archive's manifest and every file's sha256, checks the secret key (--key-file, else the one already in the state directory; it must match the manifest's fingerprint and decrypt the store, and backups made before 0.18 carry their own), restores the database and secrets into the state directory (--force replaces an existing database), applies any newer migrations, and verifies the ledger chain and that its head matches the manifest. office.yaml from the backup (mode 0644: it holds no secrets, and the service user must read it) is written to the office repo if it has none, so on a fresh machine --dir names the directory to create it in; otherwise it goes next to the state as office.yaml.from-backup. Every restore also clears the record of what was provisioned, so the next reconcile re-creates agent OS users and vault checkouts (a no-op on the same machine). If the chain verifies, it ledgers office.restored.

--with-forge also restores the bundled Gitea from the <file>.forge.tgz next to the backup. It refuses if the backup has no forge archive, if the archive's sha256 doesn't match the manifest, or if it contains any path outside /var/lib/gitea and /etc/gitea/app.ini. Then it stops Gitea, replaces /var/lib/gitea, extracts the archive, gives both paths back to git:git, and starts Gitea.

--from-remote downloads a copy from the backup.remote bucket into a private temporary directory, decrypts it (with --key-file, else the state directory's secrets.key; --passphrase-file for copies made with encryption: passphrase), then restores it as above; with --with-forge it fetches the forge archive too. Nothing is restored unless decryption authenticates every byte. It reads only office.id and backup.remote from office.yaml, so on a new machine a stub with those two keys is enough, with the bucket credentials in AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY. See Restore from the bucket.

officectl halt / resume#

officectl halt [--reason text]
officectl resume

halt sets the office-wide emergency stop in the database and ledgers office.halted (actor cli:<user>). The running server sees it within a few seconds: it kills every running and queued run and refuses new ones, and every page shows a banner. resume lifts it (office.resumed); runs the halt killed are not restarted. Settings → Emergency stop does the same from the web app (owner and admins). Run it as the office user, like other commands that read the state directory. See Stop an agent now.

officectl upgrade#

officectl upgrade <version> [--no-install] [--yes] [--no-backup] [--user office]

First it reads the target's CHANGELOG.md (with npm pack, before anything changes) and prints the notes for every release between the installed version and the target. If one of them has Breaking changes it asks for confirmation on a terminal, and refuses without --yes when run from a script. If the notes can't be fetched it warns and carries on.

Then it takes a backup (in backup.dir, default <state>/backups; --no-backup skips it and makes rollback impossible), sets the @agent-office/platform version in the office repo's package.json, runs npm install, then runs the new package's database migrations and ledgers office.upgraded (with the releases crossed and the number of breaking changes). --no-install only edits package.json and migrates with the installed package. Run as root, it then makes the platform readable by the office user where it isn't: if anything in the global $(npm root -g)/@agent-office or in the office repo's node_modules is readable by root only, it runs chmod -R a+rX on that directory, then checks sudo -u <user> officectl --version (--user, default office) and warns with the fix if it still fails. Afterwards: commit package.json and package-lock.json as a PR on the office repo, restart the service, and run officectl doctor, officectl verify and officectl smoke. See Upgrades.

officectl rollback#

officectl rollback [--yes] [--no-install] [--json]

Undoes the last officectl upgrade: restores the backup it took (migrations of the newer version are not applied), pins the previous version in package.json, runs npm install (skip with --no-install) and ledgers office.rolled_back. Stop the service first. Asks for confirmation on a terminal; needs --yes from a script. See Roll back.

officectl ledger#

officectl ledger export [--since <seq>] [--out file.jsonl]
officectl ledger verify [--json]

export writes every ledger entry after --since (default: all), oldest first, one JSON object per line with seq, ts, actor, on_behalf_of, action, target, data, prev_hash and hash, to stdout or to --out (mode 0600). verify recomputes the hash chain and exits 1 if it's broken. Run both as the office user. See Stream it to your SIEM.

officectl changelog#

officectl changelog [--since <version> | --all] [--json]

Prints the release notes shipped in the installed platform package: the latest release by default, every release newer than --since, or all of them. The same notes are on Settings → About this release and the Changelog page.

officectl status#

officectl status [--json]

Prints each agent's role, department, status, runs today and spend today; today's run counts (total, running, queued); today's total spend; and the ledger's entry count, head and last anchor. "Today" is in the office timezone.

officectl invite#

officectl invite <email>

Creates a one-time sign-in link (valid 72 hours) and prints it. Send it privately. The person's roles come from access.yaml; add them there (People page) if they are missing. Ledger: human.invited.

officectl hire#

officectl hire <role> --name "Display Name" --slug slug [--department d] [--manager human:<email>|agent:<slug>] [--reason text] [--as email]

Opens a hire PR on the policy repo from a role template, the same as the Hire page. --department defaults to the template's, --manager to human:<owner email>, and --as (the proposer) to the owner. Role templates: chief-of-staff, office-engineer, agent-resources, software-engineer, support-agent, marketing-writer, analyst. Ledger: policy.proposed.

officectl kit#

officectl kit list [--json]
officectl kit apply <id> [--rename handle=new-handle[:New Name]]… [--repos a,b] [--manager human:<email>|agent:<slug>] [--reason text] [--as email] [--json]

list shows the starter kits in the installed platform: id, personal or company, the agents, and what the kit does.

apply opens one pull request on the policy repo with every hire, routine, event rule and handbook page of the kit, the same as Apply on the Starter kits page. Merging it approves them all.

Ledger: policy.proposed (kind: kit).

officectl eval#

officectl eval <agent> [--ref <branch>] [--timeout 900] [--no-wait] [--as email] [--json]

Runs every eval in agents/<agent>/evals/ against the agent's version at --ref (a policy branch or commit, default main; the evals come from the same commit), the same as Run evals on the agent desk. The office server executes the runs, so it must be running; the command waits until every eval is graded, prints each check with its result and reason, then the score. See Evals and the verifier.

Exit code 0 when no check failed (skipped rubric checks don't fail), 1 otherwise. Ledger: eval.started, then eval.finished (written by the server).