Orgonaut CLI

Orgonaut CLI is the first-party command-line client for the REST API.

If you use Codex or Claude Code, you can also install the optional orgonaut-cli skill. That companion SKILL.md teaches the agent the safe login flow, the read-versus-scenario-write guardrails, and the best discovery commands for the shipped CLI surface.

For normal use, it is installed as a standalone macOS or Linux binary from the hosted installer:

curl -fsSL https://app.orgonaut.co/cli/install.sh | sh

Authentication uses browser OAuth with PKCE by default. The CLI opens your tenant in the browser, completes the OAuth flow against the tenant-hosted /cli/oauth/* endpoints, and stores the resulting tenant-scoped token locally. Manual --token login remains available for CI or headless environments.

During sign-in, the browser shows a short first-party consent summary and then a confirmation page before returning you to the terminal. You do not need to inspect the raw localhost callback URL or the full internal scope list to finish setup.

Use it when you want:

• repeatable reads from Live without using the browser
• scenario creation, submission, and reporting from scripts or terminals
• scenario-safe actor, position, placement, and compensation changes
• deterministic JSON output for local automations or agents

What v1 includes

Command groups:

• auth
• context
• live
• scenario
• refs department-types
• report
• doctor
• commands

V1 is intentionally scoped.

Included:

• live reads for actors, teams, departments, positions, and org units
• scenario lifecycle commands for list, create, show, tasks, submit, and delta
• reporting reads for lineage, snapshots, org-unit metrics, roster, and velocity
• scenario-safe writes for actors, positions, placements, and compensations
• department-type search and create

Not included:

• baseline mutations from the CLI
• scenario approval
• scenario promotion
• snapshot restore
• team, department, org-unit, or initiative writes

Safety rules

cli.access tokens are server-restricted.

That means:

• live baseline reads are allowed
• scenario-safe writes are allowed only inside an active scenario
• baseline mutations are denied even if the token also has broader abilities
• scenario approval, promotion, and snapshot restore are denied

This is enforced on the server, not only in the CLI.

Quick start

Install the binary:

curl -fsSL https://app.orgonaut.co/cli/install.sh | sh

Log in with browser OAuth:

orgonaut auth login --tenant acme

Check the saved profile and token:

orgonaut doctor
orgonaut context show

Install the optional companion skill for Codex:

mkdir -p ~/.codex/skills/orgonaut-cli
curl -fsSL https://app.orgonaut.co/cli/skills/latest/orgonaut-cli/SKILL.md \
  -o ~/.codex/skills/orgonaut-cli/SKILL.md

Or install the same hosted skill for Claude Code:

mkdir -p ~/.claude/skills/orgonaut-cli
curl -fsSL https://app.orgonaut.co/cli/skills/latest/orgonaut-cli/SKILL.md \
  -o ~/.claude/skills/orgonaut-cli/SKILL.md

Install

The recommended install path uses the hosted installer:

curl -fsSL https://app.orgonaut.co/cli/install.sh | sh

That script selects the correct macOS or Linux binary and installs orgonaut into /usr/local/bin by default.

If you need a specific version or a custom install directory:

curl -fsSL https://app.orgonaut.co/cli/install.sh | ORGONAUT_VERSION=v0.1.2 sh
curl -fsSL https://app.orgonaut.co/cli/install.sh | ORGONAUT_INSTALL_DIR=$HOME/.local/bin sh

For local or preview environments, point the installer at the local app host:

curl -fsSL http://app.orgonaut.test/cli/install.sh | ORGONAUT_INSTALL_BASE_URL=http://app.orgonaut.test sh

Optional Codex and Claude Code skill

The hosted CLI release also publishes the optional orgonaut-cli skill manifest. Install it if you want Codex or Claude Code to use the CLI with the same tenant-first login flow, safety guidance, and command-discovery hints that engineering ships with the CLI itself.

Install the latest skill for Codex:

mkdir -p ~/.codex/skills/orgonaut-cli
curl -fsSL https://app.orgonaut.co/cli/skills/latest/orgonaut-cli/SKILL.md \
  -o ~/.codex/skills/orgonaut-cli/SKILL.md

Install the latest skill for Claude Code:

mkdir -p ~/.claude/skills/orgonaut-cli
curl -fsSL https://app.orgonaut.co/cli/skills/latest/orgonaut-cli/SKILL.md \
  -o ~/.claude/skills/orgonaut-cli/SKILL.md

Install a specific released version:

mkdir -p ~/.codex/skills/orgonaut-cli
curl -fsSL https://app.orgonaut.co/cli/skills/vX.Y.Z/orgonaut-cli/SKILL.md \
  -o ~/.codex/skills/orgonaut-cli/SKILL.md

Or with Claude Code:

mkdir -p ~/.claude/skills/orgonaut-cli
curl -fsSL http://app.orgonaut.test/cli/skills/latest/orgonaut-cli/SKILL.md \
  -o ~/.claude/skills/orgonaut-cli/SKILL.md

Once installed, ask your agent to use the orgonaut-cli skill when it needs to:

• log in with orgonaut auth login --tenant <slug>
• run orgonaut doctor and orgonaut context show after login
• prefer live reads for inspection and scenario context for writes
• discover the shipped surface with orgonaut commands --json or orgonaut help <path> --json

Log in

CLI v1 uses browser OAuth by default. Most users should use this flow instead of creating a token manually.

orgonaut auth login --tenant acme

If you omit optional flags, the CLI only needs the tenant slug. It derives the tenant host as https://<tenant>.orgonaut.co, opens the browser there, and saves a sensible local profile name automatically.

The CLI opens your browser on the tenant host, shows a short consent summary for the first-party CLI client, exchanges the PKCE authorization code for a tenant-scoped token, and stores that token in the system keychain when available.

The consent screen is intentionally brief. It summarizes the access the shipped CLI needs and hides raw callback details such as http://localhost:7637/callback and the full scope wall that Passport uses internally.

After you approve the request, the browser returns control to the local CLI running on your device so the sign-in flow can finish automatically. You should see a short success or failure confirmation page in the browser before closing the tab.

The browser OAuth flow requests the default CLI v1 ability bundle for you, including cli.access and the standard read/write abilities needed by the shipped command surface.

Use --name only if you want to override the default saved profile label for the local machine.

Manual token login

If you need a headless or CI-safe path, keep using --token:

orgonaut auth login \
  --tenant acme \
  --token '<bearer-token>'

Quote the token value when you paste it into the shell. Orgonaut bearer tokens contain |, which zsh treats as a pipe operator when the token is unquoted.

Manual tokens must still include:

• cli.access
• the exact read and write abilities the workflow needs

Examples:

• read-only org review: cli.access, actors.read, teams.read, departments.read, positions.read, org-units.read, org-metrics.read, lineage.read, scenarios.read
• scenario modelling: add actors.create, actors.update, actors.delete, positions.create, positions.update, positions.delete, placements.write, placements.delete, and scenarios.update as needed

CLI preflight fails if the pasted token does not explicitly include cli.access.

If you see keytar.getPassword is not a function or keytar.setPassword is not a function, rerun the CLI command with ORGONAUT_CLI_DISABLE_KEYTAR=1 to bypass the OS keychain and use the CLI's local secrets file.

After login, run:

orgonaut doctor
orgonaut context show

Work with context

The CLI stores local profiles by saved profile name. Each profile records its base URL, tenant slug, and sticky context.

Each profile keeps sticky context:

• live
• scenario

Switch context with:

orgonaut context scenario list
orgonaut context scenario use draft-plan
orgonaut context mode live

Override context for one command with:

• --live
• --scenario <id-or-slug>

Full command reference

The CLI ships a catalog-backed command index. You can inspect it locally with:

orgonaut commands
orgonaut help scenario positions

The supported v1 command set is:

Auth

Context

Live reads

Scenario lifecycle

Scenario actors

Scenario positions

Scenario placements

Scenario compensations

Reference data

Reports

Utilities

Common examples

Read Live:

orgonaut live actors list
orgonaut live org-units tree
orgonaut report org-units summary

Model inside a scenario:

orgonaut scenario create --name "Q3 restructure"
orgonaut context scenario use q3-restructure
orgonaut scenario actors create --set first_name=Maeve --set last_name=Byrne --set email=maeve@example.com
orgonaut scenario positions create --input position.json
orgonaut scenario submit

Read reports and history:

orgonaut report teams velocity 42
orgonaut report scenarios lineage
orgonaut report scenarios snapshots

JSON output for automation

Place --json before the command path for the stable automation envelope:

orgonaut --json doctor

Every command returns:

{
  "ok": true,
  "command": "doctor",
  "data": {},
  "error": null,
  "next_actions": [],
  "context": {}
}

Use commands --json and help <path> --json for machine-readable discovery.

Related docs

• API reference
• Connect MCP clients
• Scenario overview
• Users and Access