CLI Reference

Every armoriq command with flags, expected output, and copy-pasteable examples. login, orgs, switch-org, init, validate, register, status, logs, whoami, logout.

The armoriq CLI has ten subcommands. This page documents each one with its flags, a typical example, and the output you should expect.

armoriq login       [--org <name-or-id>]
armoriq logout
armoriq whoami
armoriq orgs
armoriq switch-org  <name-or-id> [--key-name <label>]
armoriq init        [--output armoriq.yaml]
armoriq validate    [--config armoriq.yaml]
armoriq register    [--config armoriq.yaml] [--dry-run]
armoriq status
armoriq logs        [--follow]

All commands exit 0 on success and print errors to stderr with a non-zero exit code on failure.

Authenticate your developer workstation. Opens a browser tab, signs you in via OAuth device-code flow, mints a new API key, and saves it to ~/.armoriq/credentials.json.

Flags:

--org <name-or-id> (optional) — pre-select a specific organization on the approval page. Accepts the org's exact name or its UUID. Useful when you know ahead of time which org this machine should be scoped to.

Example:

# Basic login
armoriq login

# Log in scoped to a specific org
armoriq login --org "ACME Corp"
armoriq login --org 144e79f7-7873-41f1-aed8-0ebb5b108200

Output:

  ArmorIQ Login

  Opening browser...

  If the browser didn't open, visit:
    https://platform.armoriq.ai/auth/device?code=XXXX-XXXX

  Confirm this code in your browser: XXXX-XXXX

  Waiting for authorization... ✔

  ✔ Logged in as alice@acme.com (org: 144e79f7-...)
  ✔ API key saved to /Users/alice/.armoriq/credentials.json

Each armoriq login mints a new API key. Old keys remain valid until you delete them from the API Keys dashboard. If you're logging in from a new machine, consider rotating the old machine's key afterwards.

`armoriq logout`

Deletes the local credentials file. Does not revoke the server-side key — open the API Keys dashboard to fully revoke.

Example:

armoriq logout
# → ✔ Credentials removed from /Users/alice/.armoriq/credentials.json

`armoriq whoami`

Prints your current identity from the credentials file. No network call.

Example:

armoriq whoami

Output:

  ArmorIQ Credentials

  Email:    alice@acme.com
  API Key:  ak_live_xxxxxxxx...
  User ID:  8c0b55f8-b052-4041-9d15-02835bd919ad
  Org ID:   144e79f7-7873-41f1-aed8-0ebb5b108200
  Saved at: 2026-04-22T08:48:08+00:00
  File:     /Users/alice/.armoriq/credentials.json

If you're not logged in, you'll see Not logged in. Run \armoriq login` to authenticate.`

`armoriq orgs`

Lists every organization your account belongs to. Marks the active org with ✓.

Example:

armoriq orgs

Output:

  NAME         ORG_ID                                ROLE        MEMBERS
  ----------------------------------------------------------------------
✓ ACME Corp    144e79f7-7873-41f1-aed8-0ebb5b108200  org_admin   11
  Demo Org     d8ec1877-d828-4f78-9f03-f374a01e55ae  org_admin   10
  Side Project 50901712-32e6-4d45-8f2a-83a56b46653c  iam_admin    2
  Stripe Demo  fa2be516-9ff3-4328-952f-10a3420cd249  org_admin    7

Active org is marked with ✓. Switch with `armoriq switch-org <name-or-id>`.

`armoriq switch-org`

Switch scope to a different organization. Mints a fresh API key bound to the target org and updates ~/.armoriq/credentials.json.

Arguments:

<name-or-id> (required, positional) — target organization. Accepts either the exact organization name or the UUID.

Flags:

--key-name <label> (optional) — name to attach to the newly minted key. Defaults to cli-YYYY-MM-DD.

Example:

# Switch by name
armoriq switch-org "Stripe Demo"

# Switch by UUID
armoriq switch-org fa2be516-9ff3-4328-952f-10a3420cd249

# Switch with a custom key label
armoriq switch-org "Stripe Demo" --key-name "macbook-pro"

Output:

✓ Switched to Stripe Demo (org_id=fa2be516-9ff3-...)
✓ New API key saved.

If you had an agent registered (armoriq register) in the previous org, its state is cleared — re-run armoriq register to bind your agent to the new org.

Each switch-org mints a fresh API key. The previous key is still valid until you revoke it from the dashboard.

`armoriq init`

Interactive wizard that generates an armoriq.yaml config file. Prompts you for API key, agent ID, user ID, environment, and the MCP servers your agent calls (probing each to discover its tools).

Flags:

--output <path> (optional) — where to write the YAML. Defaults to armoriq.yaml in the current directory.

Example:

cd my-project/
armoriq init --output agent.yaml

Prompts (with defaults in brackets):

ArmorIQ CLI v1.0.0

API Key [$ARMORIQ_API_KEY]: <press Enter>
Agent ID [my-agent]: booking-bot
User ID [default]: service-account
Environment [sandbox]: sandbox
✓ Credentials verified
Add an MCP server? (y/n) [n]: y
MCP Server URL: https://mcp.travel.example
Server ID [travel]: travel-mcp
Auth type [none/bearer/api_key] [none]: bearer
Bearer token (value or $ENV_VAR): $TRAVEL_MCP_TOKEN
Description []: Flight and hotel MCP
✓ Connection verified. 8 tools discovered:
    book_flight, cancel_booking, search_hotels, ...
Add an MCP server? (y/n) [n]: n
Generated agent.yaml
Next: edit the policy block, then run `armoriq register`

See the YAML reference for every field the generated file contains.

`armoriq validate`

Checks an armoriq.yaml for errors before shipping it. Parses the file, authenticates the API key against the backend, probes each MCP server to refresh the tool list, and validates that every policy.allow / policy.deny entry references a tool that actually exists.

Flags:

--config <path> (optional) — config file to validate. Defaults to armoriq.yaml.

Example:

armoriq validate --config agent.yaml

Output on success:

✓ Config syntax valid
✓ API key authenticated
✓ travel-mcp MCP reachable (8 tools)
✓ Policy references valid tool names
Ready to register.

Output on failure — bad policy reference:

✓ Config syntax valid
✓ API key authenticated
✓ travel-mcp MCP reachable (8 tools)
Error: Policy references invalid tools: allow ref not found: travel-mcp.book_flight_typo

Run validate in your CI pipeline before register to catch typos and stale tool names early.

`armoriq register`

Pushes your armoriq.yaml to the ArmorIQ control plane. Upserts the agent row, MCP server rows, and policy rows for your organization. Idempotent — safe to re-run on every yaml change.

Flags:

--config <path> (optional) — config file to push. Defaults to armoriq.yaml.
--dry-run — skip the network call, only write the local registration state file. Useful to test your config without touching the backend.

Example:

armoriq register --config agent.yaml

Output:

Registering with ArmorIQ control plane...
✓ Agent booking-bot registered
✓ MCP server travel-mcp registered (8 tools)
✓ Policy applied (3 allowed, 0 denied)
✓ Proxy endpoint: https://proxy.armoriq.ai

Your agent is ready. Use the SDK as usual:

  from armoriq_sdk import ArmorIQClient
  client = ArmorIQClient.from_config("agent.yaml")

Each successful register writes ~/.armoriq/state.json with the registration metadata (agent ID, timestamp, proxy URL, registered MCP server IDs).

`armoriq status`

Prints your last successful register — agent, user, environment, timestamp, proxy endpoint, and MCP servers. No network call.

Example:

armoriq status

Output:

Agent: booking-bot
User: service-account
Environment: sandbox
Registered at: 2026-04-22T09:19:29+00:00
Proxy endpoint: https://proxy.armoriq.ai
MCP servers: travel-mcp

If you haven't registered (or if switch-org cleared the state), you'll see No local registration state found. Run \armoriq register` first.`

`armoriq logs`

Prints the local activity log — every CLI operation (login, register, switch-org, etc.) written as one JSON line per event to ~/.armoriq/cli.log.

Flags:

--follow — stream new log lines as they're written (like tail -f). By default, prints the file and exits.

Example:

# Dump all history
armoriq logs

# Stream live
armoriq logs --follow

Output:

[2026-04-22T08:48:08+00:00] login: {"email": "alice@acme.com", "org_id": "144e79f7-..."}
[2026-04-22T09:15:22+00:00] orgs: {"count": 4}
[2026-04-22T09:19:11+00:00] switch-org: {"org_id": "fa2be516-...", "org_name": "Stripe Demo", "cleared_state": true}
[2026-04-22T09:19:29+00:00] register: {"agent_id": "booking-bot", "environment": "sandbox", ...}

Useful for "what did I do yesterday?" debugging. For platform-side audit, use Audit Logs.

Common workflows

First time, single environment

pipx install armoriq-sdk
armoriq login
armoriq init
# edit armoriq.yaml if needed
armoriq validate
armoriq register

Iterating on policy

# edit armoriq.yaml — add a new tool to policy.allow
armoriq validate    # catches typos
armoriq register    # idempotent — updates in place

Switching between organizations

armoriq orgs                          # see what's available
armoriq switch-org "Stripe Demo"      # mint a new key scoped to that org
armoriq register --config agent.yaml  # re-bind your agent to the new org

CI pipeline

# .github/workflows/deploy-agent.yml
- run: pip install armoriq-sdk
- run: armoriq validate --config agent.yaml
  env:
    ARMORIQ_API_KEY: ${{ secrets.ARMORIQ_API_KEY }}
- run: armoriq register --config agent.yaml
  env:
    ARMORIQ_API_KEY: ${{ secrets.ARMORIQ_API_KEY }}

No armoriq login needed in CI — the env var is the only key source.

On this page