CLI Reference

The aios CLI runs on Node 22. Install it from aios-workspace:

# From inside an aios-workspace clone:
npm link   # or add to PATH: export PATH="$PWD/bin:$PATH"

Your workspace’s aios.yaml uses a restricted YAML subset — flat scalars and string lists only. The API key never goes in this file; api_key_env holds the name of the environment variable that carries it, and the secret itself lives in a gitignored .env. A validator hard-fails if api_key_env looks like a value rather than a name.

version: 1
brain_url: https://your-brain.example.com
# Optional legacy compatibility hint. The API key owns team identity.
# team_id: your-team-id

# The NAME of the env var holding your key — never the key itself.
api_key_env: AIOS_API_KEY

# Which access tiers may leave this machine. `admin`/`private` are rejected here.
sync_tiers:
  - team
  - client # or `company` — both are canonically `external`


# Paths considered for sync. A file still needs an `access:` tier within
# sync_tiers to actually push — untagged files are blocked by default.

sync_include:
  - 0-context
  - 1-inbox/transcripts
  - 2-work
  - 3-log/decision-log.md
  - 3-log/tasks-team.md
  - 3-log/ai-spend.md
  - 4-shared
  - .claude/memory

sync_exclude:
  - 5-personal

Leave brain_url empty to run fully offline — every other part of the workspace works without a Team Brain.

Commands

`aios onboard`

Inspect first, then guide the Personal / Join / Create decision. The inspect form is dependency-free and read-only. The interactive form pauses before updates, origin trust, secrets, or sharing and never pushes during onboarding.

aios onboard --inspect --json
aios onboard

For an existing workspace, aios update --preview performs the safety check and shows the proposed managed-file changes. Apply only after reviewing that preview.

`aios update`

Preview or apply managed scaffold updates with a three-way merge that preserves local customizations.

aios update --preview
aios update

The preview is read-only and includes the update safety check. Dirty, diverged, or otherwise unsafe toolkit states are refused instead of overwritten.

`aios whoami`

Validate the configured Brain origin and API key against GET /api/v1/me.

aios whoami
# → {"team":"…","actor":"…","role":"…","tier":"…"}

The API key is authoritative for team identity; team_id is optional.

`aios status`

Preview what would be pushed without sending anything.

aios status
# → Lists files that are new, modified, or unchanged since last push

`aios review`

Open the terminal Review & push panel. It uses the same plan as aios status, keeps blocked files non-selectable, and lets you toggle eligible files before a dry run or push.

aios review
# controls: <n> toggle · a all · n none · d dry-run · p push · q quit

The cockpit exposes the same default-deny plan in its Review & push tab.

`aios push`

Push tier-eligible content to the Team Brain.

aios push                    # push everything eligible
aios push --dry-run          # preview only (same as status)
aios push 2-work/retro.md   # push specific path(s)

Only files whose frontmatter access: maps to team or external are sent. Files without an allowed access: value are blocked by default.

Publish a team- or external-tier skill through the Brain, or pull one into the inbox for review. A pulled skill is executable code, so it never auto-activates: installation is a separate, explicit local step.

aios push skill <name> --dry-run  # inspect SKILL.md + shareable text references
aios push skill <name>            # publish the skill and reference manifest
aios pull skill <name>            # fetch into 1-inbox/from-brain/skills/<name>/
aios install-skill <name>         # after review, copy into .claude/skills/<name>/

Existing installed skills are not overwritten unless you deliberately pass --force to install-skill; binary or secret-bearing reference files are skipped during publication.

`aios pull`

Fetch team updates from the brain into 1-inbox/from-brain/.

aios pull
# → Downloads items updated since last pull, writes to 1-inbox/from-brain/
# → Also fetches task rows and writes them to 3-log/tasks-from-brain.md

`aios query`

Natural-language query against the Team Brain. Streams the answer.

aios query "what blocked sprint 1?"
aios query "who owns the auth decision?"

`aios export-okf`

Export a tier-filtered OKF (Open Knowledge Framework) bundle from the brain to a local directory.

aios export-okf              # exports to .aios/okf/
aios export-okf ./my-bundle  # exports to specified directory

`aios pull-bundle`

Pull the OKF link graph from the brain into .aios/bundle.json for offline traversal.

aios pull-bundle
# → Use /okf-traverse inside Claude Code to query offline

`aios graph`

Traverse the local OKF bundle and print the link graph.

aios graph
aios graph --from 2-work/retro.md   # start from a specific node

`aios assess-codebase`

Score a repo’s AM agent-readiness (L0–L5). Offline and read-only — nothing is sent anywhere.

aios assess-codebase                 # score the current repo
aios assess-codebase ./path          # score another repo
aios assess-codebase --json          # machine-readable output

`aios analyze`

Build an Agentic Maturity report from your local agent-session logs (Claude, Codex, Cursor): it computes structural signals (delegation, verification, cost, …) and places you on the AM Spine. With --push, the daily aggregate goes to the brain — ratios and counts only, never raw session text.

aios analyze                         # last 7 days, printed
aios analyze --since 30d --report     # longer window + full report
aios analyze --push                  # also POST to /api/v1/metrics (team-tier key)

`aios relay`

Run an automated Opus ↔ Cursor plan/review loop over a task: Opus plans, Cursor executes, Opus reviews, repeating for N rounds (default 3).

aios relay "add rate-limit tests"            # 3 rounds, /review-plan
aios relay "refactor parser" --rounds 2       # custom round count
aios relay "tidy imports" --dry-run           # plan/review without writing

`aios loop`

Run the verified Operator Loop: collect local evidence, create an audience-safe weekly closeout, verify it against the evidence and tier policy, then explicitly stage an approved writeback for a later aios push.

aios loop collect --weekly
aios loop manifest --explain --as team
aios loop weekly --as team
aios loop writeback <stamp>          # preview only
aios loop writeback <stamp> --local  # opt in to one destination

Collection and the owner brief are local. Shareable digests remain default-deny, verification must pass before approval, and writeback stages rather than sending. For the separate rubric-gated weekly summary harness, see Harnesses.

`aios timeline`

Render a screenshot-rich weekly “what we shipped” page from merged PRs and commits across one or more repositories. Start with a dry run; --no-shots produces code-change cards without browser capture.

aios timeline --since 7d --repo ../project --as team --dry-run
aios timeline --since 7d --repo ../site=https://example.com --as all

Output lands in .aios/timeline/<stamp>/index-<audience>.html. Team and external views come from the same dataset, but the external view includes only external-tier repositories and is withheld unless the leak gate actually runs clean.

Environment variables

Variable	Description
`AIOS_API_KEY`	Your API key. This is the default variable `api_key_env` points at — the secret lives here or in a gitignored `.env`, never in `aios.yaml`
`AIOS_BRAIN_URL`	Overrides `brain_url` in `aios.yaml`
`AIOS_TEAM`	Optional legacy override for `team_id`; the API key remains authoritative

This page covers the core operator path, not every specialist command. Run aios --help for the help text and flags in your installed release.

Complete top-level registry

The detailed sections above cover the core operator path. This inventory is generated from the command registry in the current public Workspace release, v0.10.0. Commands on untagged main are intentionally excluded until a coordinated release updates the pin.

Area	Commands
Workspace and sync	`status`, `onboard`, `connect`, `review`, `push`, `work`, `pull`, `promote`, `query`, `member`, `stakeholders`, `update`, `whoami`
Skills and context	`install-skill`, `skills`, `context-health`, `instincts`, `learn`, `consolidate-findings`
Operator loop	`loop`, `timeline`, `analyze`, `maturity-week`, `time`, `asks`, `transcripts`, `pm`, `mode`, `decisions`, `council`, `inbox`
Engineering delivery	`verify`, `assess-codebase`, `codebase-health`, `relay`, `worktree`, `rails`, `build`, `simplify`, `spec`, `pr`, `review-bugbot`, `ship`, `roadmap-run`, `delivery`, `repo-bootstrap`
Interfaces and data	`mcp`, `export-okf`, `pull-bundle`, `graph`, `catalog`, `gen-catalog`, `connector`

CLI Reference

Commands

aios onboard

aios update

aios whoami

aios status

aios review

aios push

Share, pull, and install a skill

aios pull

aios query

aios export-okf

aios pull-bundle

aios graph

aios assess-codebase

aios analyze

aios relay

aios loop

aios timeline