Commands

This reference documents NIIA 0.9.41, the current OpenCLIs release. Bare niia prints the packaged guide plus live status; niia --help is the CLI inventory and niia --mcp-schema is the generated CLI-to-MCP contract. All five published platform fragments carry the current command and guide surface.

Surface counts

Surface	Count	Contract
Top-level CLI	62	The human and shell entry points below; generated `help` is additional
Generated MCP schema	107	Supported non-recursive commands, including `niia_docs_guide`, with nested groups flattened into typed tools
Live `niia mcp`	108	The 107 generated tools plus `niia_mcp_self_status`

The counts intentionally differ. Login, setup, recursive MCP management, blocking automation, and similar lifecycle operations are CLI commands without a generated MCP tool. See the release matrix for immutable platform and payload proof.

Install and identity

openclis install niia
openclis update niia
niia --version
niia status

All 62 top-level commands

Memory, intelligence, and configuration

Command	Purpose
`niia search`	Unified search across documents, code, and git
`niia recall`	Recover prior work and synchronize memory
`niia index`	Index documents, code, git, or AI sessions
`niia status`	Show NIIA and lower-layer status
`niia gauge`	Classify a task on the entry ladder, print its proportional `[NEXT]` chain, and write the session witness
`niia finish`	Re-present the gauge promise, inspect the current Monogram close state, and write `finish.json` without gating
`niia audit-entry`	Write a report-only audit against the promise recorded for this session
`niia doctor`	Check database freshness, dirty-index driver state, routing, hooks, and witness wiring from metadata only
`niia docs`	Document search and reference navigation
`niia code`	Monogram-backed code search and graph navigation
`niia git`	Monogit-backed branch and commit structure
`niia where`	Resolve the current project identity
`niia now`	Produce a current timestamp or file-safe slug
`niia activity`	Show recent recorded activity
`niia projects`	List known projects
`niia watch`	Show recently changed files
`niia watcher`	Inspect and manage watcher paths and exclusions
`niia files`	Show frequently used files
`niia session`	Read, list, and search AI CLI sessions
`niia reindex`	Refresh the complete intelligence stack
`niia insights`	Run cross-database insight categories
`niia gaps`	Find missing, disconnected, or outdated knowledge
`niia drift`	Find files that stopped changing together
`niia chain`	Join a symbol across code, git, and documents
`niia convergence`	Compare code topics with research, plans, proofs, and docs
`niia resonate`	Diagnose infrastructure, quality delta, and consciousness state
`niia consciousness`	Search or navigate the embedded consciousness core
`niia monograph`	Read and search executable knowledge Books
`niia setup`	Install or reconcile NIIA resources without overwriting local evolution by default
`niia skills`	Inspect, adopt, or export skill drift
`niia trust`	Verify the signed OpenCLIs trust-domain registry
`niia auth`	Show current authentication state

MCP

Command	Purpose
`niia mcp-auth`	Authenticate the remote MCP surface with stored credentials
`niia mcp-run`	Call a local stdio or remote REST MCP tool as a CLI command
`niia mcp-list`	List registered local MCP services
`niia mcp`	Serve NIIA’s supported commands as typed MCP tools
`niia mcp-serve`	Serve another CLI as MCP, using its schema when available
`niia mcp-add`	Register a local MCP service
`niia mcp-session`	Keep a stateful MCP service alive across calls

Terminal sessions and automation

Command	Purpose
`niia write`	Write bytes to an existing PTY session
`niia ask`	Send, wait, and extract one answer
`niia follow-up`	Guard a follow-up on evidence that the previous answer exists
`niia expect-screen`	Assert that the visible screen contains text
`niia expect-history`	Assert against scrollback history
`niia expect-system`	Assert against a provider-owned transcript
`niia step`	Run one guarded send → expect → cleanup step
`niia scenario`	Run JSON or JSONL terminal steps
`niia wait-idle`	Wait for terminal output to settle
`niia get-answer`	Extract an answer from the rendered terminal
`niia get-answer-system`	Parse an answer from a provider-owned transcript or output file
`niia health`	Distinguish live, drivable sessions from stale ones
`niia auto`	Repeatedly inject a command into a session or a newly supervised session
`niia run`	Run a `connector.json` pipeline

OS, transport, and identity

Command	Purpose
`niia observe`	Read the operating system through NIIA’s observe gate
`niia control`	Perform an authorized operating-system action
`niia serve`	Forward headless server lifecycle to Monosystem
`niia daemon`	Manage the Monosystem machine-gateway daemon
`niia devices`	List and manage registered devices
`niia remote`	Diagnose or interact with another machine
`niia mailbox`	Read and synchronize PTY result messages
`niia login`	Authenticate by OTP or supported credential flow
`niia logout`	Revoke local login state and stop owned services

Work-entry self-drive

The four self-drive commands carry the entry discipline as observable session state. They advise, record, and report; they do not seize control from the user or turn a missing step into a command gate.

niia gauge --rung MODERATE "update the parser and its public contract"
niia gauge --re "the change now crosses the release workflow"
niia finish
niia audit-entry
niia doctor

`niia gauge [OPTIONS] [TASK]...`

gauge combines prompt signals with the deployed ~/.niia/routing.toml and records the verdict in gauge.json. An explicit --rung is sovereign: the user’s TRIVIAL, MODERATE, HIGH, or CLAIM choice wins. Destructive or live-surface words still emit [CONSENT], and any fan-out recommendation is a proposal rather than authorization.

Rung or lane	Output contract
`TRIVIAL`, `LOOKUP`, `DOC`, `CONVERSATIONAL`, `CONTINUATION`	Silent success with an empty `[NEXT]` promise, unless a consent warning must surface
`MODERATE`	Recall evidence, prepare against real code, enter the Monogram sequence, implement, then close
`HIGH`	Research with a FINDINGS ledger, prepare, implement, then close
`CLAIM`	Run the proof workflow to Q.E.D. before relying on the claim, then close

--hook reads a Claude Code or Codex hook event from stdin. Hook modes keep exit zero on internal failure while recording stderr and ~/.niia/hook-error.log. --session-start arms the ladder or restores the recorded bracket after compaction. --static prints the generic ladder without signal probes. --re <reason> records an ESCALATE or DE-ESCALATE history event, and --session <id> selects the witness explicitly. --transcript <path> supplies the transcript for an ad-hoc or benchmark run when hook stdin did not provide one; this unblocks the promise-derived audit without copying the transcript into gauge.json.

Put every gauge option before TASK. Because task text is a trailing positional, tokens after it are task text, not flags.

Inside a Git worktree, witnesses live under <repo>/.niia/session-order/<session>/; outside Git they live under ~/.niia/session-order/<cwd-hash>/<session>/. The directory contains gauge.json. History is append-only, including across silent side lanes. Only a session id carried by hook stdin may atomically move current; CLI --session, ad-hoc, and static verification runs cannot retarget the live session pointer.

`niia finish [--session <id>]`

finish reprints the rung, re-gauge history, and every promised [NEXT] step. When the promise included a Monogram sequence, it reports the newest sequence phase and calls an unfinished phase UNMET. HIGH work also receives the open-FINDINGS reminder. The command then writes finish.json and points to audit-entry; it records and re-presents unmet work but never blocks closing.

`niia audit-entry [--session <id>] [--hook]`

The audit judges only the machine-gauged promise for this session. Depending on the rung, it checks that the injected contract reached the transcript before the first product edit, evidence preceded editing, HIGH research preceded the build, CLAIM work contains proof, and no product mutation followed finish. Re-gauge escalation is recorded as an event, never a violation. Results go to audit-report.json; --hook stays silent. The current transcript reader supports Claude JSONL and ad-hoc witnesses. Codex transcript audit is deliberately SUSPENDED until its reader ships; that is an explicit unverified boundary, not a passing verdict.

`niia doctor`

doctor is a metadata-only, sub-second estate check. It uses the newest of a SQLite database and its WAL/SHM sidecars. For dirty indexing it prefers the watcher’s own verdict, otherwise reads only the final 64 KiB of the launchd driver log and detects repeated deferral. It checks the routing registry, UserPromptSubmit, SessionStart, SessionEnd, recent hook errors, the fallback flag, and witness-directory writability. Database-family ages below 24 hours are OK, 24–72 hours are WARN, and 72 hours or more are RED. Every warning or failure row carries its own [NEXT] recovery command. It does not scan or rewrite an index; the sole write is a temporary .doctor-probe created and removed inside the witness directory to prove that the directory is writable.

Search, index, and analysis

niia search "session gateway"
niia search "session gateway" --docs
niia search "create_session" --code --recent
niia recall
niia index . --docs
niia index --sessions
niia index --dirty
niia index --dirty --dirty-project <project-root>
niia reindex
niia reindex --auto --max-projects 3 --dry-run

niia index --dirty consumes watcher events into the participating document, code, git, and knowledge indexes. Registration catch-up can still refresh a project root when no event is pending; a failed lane keeps its cursor for retry rather than pretending the event was consumed.

niia insights
niia gaps
niia drift src/main.rs
niia chain create_session --depth 3
niia convergence
niia resonate

Document commands

Command	Purpose
`niia docs guide`	Read the embedded `self-drive` or `changelog` guide; omit the topic to list available guides
`niia docs search`	Search documents; `--read` also prints the top document
`niia docs tree`	Follow forward or backward document references
`niia docs list`	List indexed documents by document type
`niia docs peek`	Preview headings and structure
`niia docs read`	Read a document or one section
`niia docs deps`	Show outgoing document references
`niia docs rdeps`	Show reverse references
`niia docs bridge`	Find similar documents
`niia docs stats`	Show document-index statistics

niia docs search "session ownership" --idf --read
niia docs tree SKILL.md --depth 2
niia docs read SKILL.md "Workflow"

Code commands

niia code is the integrated Monogram surface. Use standalone Monogram for region ranking, coupling, format traces, deep semantics, and possibility bands.

Command	Purpose
`niia code search`	Search code files
`niia code context`	Convert an intent query into entry symbols, source, and one-hop graph context
`niia code chain`	Show a flat caller or callee chain
`niia code tree`	Show a hierarchical call tree
`niia code deps`	Show file dependencies
`niia code rdeps`	Show reverse dependencies
`niia code symbols`	Search symbol definitions
`niia code stats`	Show code-index statistics

niia code context "where sessions are created" --symbols 8 --lines 40
niia code chain create_session --callers --depth 2 --strict

Git commands

Command	Purpose
`niia git query`	Find branches containing a commit
`niia git branches`	List branches in the cached structure
`niia git compare`	Compare two branches
`niia git diff`	Compare two commits
`niia git stats`	Show git-index statistics

Session commands

Command	Purpose
`niia session read`	Read one discovered provider session
`niia session search`	Search the indexed session corpus
`niia session list`	List recent sessions by provider

niia session list --tool codex -n 5
niia session read latest --tool grok --full
niia session search "release boundary" -n 10

See AI sessions for the provider and PTY boundaries.

Consciousness and Monograph

niia consciousness "entry discipline"
niia consciousness --list
niia consciousness --map
niia consciousness NIIA_IDENTITY --chain

Command	Purpose
`niia monograph match`	Resolve a band signal or CWE to the primary knowledge entry
`niia monograph read`	Read an entry by exact ID
`niia monograph search`	Keyword fallback search
`niia monograph resonate`	Rank and spread through the Book reference graph
`niia monograph scan`	Scan an edited file and attach matching knowledge entries
`niia monograph related`	Follow typed causal edges
`niia monograph toc`	Show a Book’s chapter table of contents
`niia monograph books`	List registered Books
`niia monograph open`	Route a query to the best Book

Skill reconciliation

Command	Purpose
`niia skills diff`	Compare installed skills and agents with the embedded bundle
`niia skills adopt`	Record a non-writing drift baseline
`niia skills export`	Copy locally evolved material into an explicit staging directory

niia setup --dry-run
niia setup --force
niia setup use openclis
niia setup use monolex
niia skills diff --json --orphans
niia skills export --into ./niia-skills-export --dry-run

Setup preserves locally evolved files by default. Destructive replacement requires an explicit force choice. setup use owns only the PATH-facing NIIA selector. On Unix, OpenCLIs uses a symlink to ~/.openclis/bin/niia; on Windows it copies niia.exe to %USERPROFILE%\.niia\bin\niia.exe. Version 0.9.41 writes no ownership marker: the Unix status detector recognizes the OpenCLIs symlink target, while the Windows regular copy is reported as monolex. Invoke the newly installed OpenCLIs executable after a Windows update when that PATH-facing copy must be refreshed:

& "$HOME\.openclis\bin\niia.exe" setup use openclis
where.exe niia
niia --version

MCP commands

MCP service to CLI

niia mcp-list
niia mcp-add playwright npx @anthropic/mcp-playwright -- --desc "Browser automation"
niia mcp-run chrome-devtools _help
niia mcp-run chrome-devtools _help:navigate_page
niia mcp-run chrome-devtools navigate_page url=https://monolex.ai
niia mcp-run local-service structured 'items:=["one","two"]'

Use _help and _help:<tool> for service/schema help. --help is the NIIA command’s own Clap help and is not a wrapped tool lookup.

CLI to MCP

niia mcp
niia --mcp-schema
niia mcp-serve monogram
niia mcp-serve <any-cli>

The generic bridge uses <tool> --mcp-schema when present; otherwise it exposes one passthrough tool returning the CLI’s raw output.

Persistent sessions

niia mcp-session start chrome-devtools
niia mcp-session status chrome-devtools
niia mcp-session list
niia mcp-session stop chrome-devtools

MCP isError, JSON-RPC, transport, quota denial, authentication, and REST failures exit non-zero. With --json, an MCP isError payload remains on stdout before the non-zero exit.

Terminal driving

niia health --session <ID>
niia write --session <ID> $'claude\r'
niia wait-idle --session <ID>
niia get-answer --session <ID> "your exact prompt"

niia ask --session <ID> "run the focused tests"
niia follow-up --session <ID> "summarize failures" --expect-last "tests"

Use \r, not \n, as Enter for raw-mode terminal applications.

Assertions and scenarios

niia expect-screen --session <ID> "Finished" --show
niia expect-history --session <ID> "Finished" --tail 100 --show
niia expect-system --cli codex --transcript <file> "done"
niia step --session <ID> --send "cargo check" --expect "Finished" --read screen
niia scenario --session <ID> <scenario.jsonl>

Timeouts and failed guards return non-zero. niia get-answer reads the live rendered screen; niia get-answer-system reads a provider-owned transcript. Choose the evidence source that owns the answer you need.

Scheduling and pipelines

niia auto --session <ID> --every 5m --run "cargo check" --times 3 --log
niia auto --new --where <project> --with claude --model opus --effort max --every 1h --run "continue"
niia run pipeline.connector.json user_query="search term"

With --new, NIIA delegates session startup to Monosystem. It does not forward JWT or policy secrets through child arguments or environment variables.

Observe commands

Command	Purpose
`niia observe snapshot`	Combine windows, accessibility context, and clipboard state
`niia observe targets`	Build an AX + OCR interaction map with stable target handles
`niia observe windows`	List windows
`niia observe ax-tree`	Read an app’s accessibility tree
`niia observe capture`	Capture a display or region
`niia observe query`	Query a supported app data source
`niia observe search`	Search Spotlight
`niia observe log`	Read recent app logs
`niia observe defaults`	Read app preferences
`niia observe process`	Inspect processes
`niia observe network`	Inspect network state
`niia observe lsof`	Inspect files or ports owned by a process
`niia observe permissions`	Report OS permissions

Other read-only Kernel CLI commands can pass through niia observe. NIIA rejects write commands on this entrance.

Control commands

niia control unlock --scope observe --duration 30m
niia control unlock --scope full --duration 30m
niia control status
niia control lock all

Command	Purpose
`niia control status`	Show observe and control grant state
`niia control lock`	Revoke one or both scopes
`niia control ax-press`	Press an accessibility element by title
`niia control ax-set`	Set an accessibility value
`niia control act`	Resolve a target handle, reject stale snapshots, act, and verify
`niia control click`	Click coordinates
`niia control type`	Type text, optionally after activating an app
`niia control key`	Press a key combination
`niia control script`	Run AppleScript or JXA
`niia control open`	Open a URL scheme
`niia control defaults-write`	Write an app preference
`niia control shortcut`	Run a macOS Shortcut
`niia control notify`	Send a notification
`niia control kill`	Terminate a process

Other write-capable Kernel CLI operations pass through niia control only after the correct NIIA grant exists. control act --dry-run resolves and reports the planned action without actuating it.

Remote and transport

The transport commands are first-class NIIA names but are currently owned by Monosystem:

niia login
niia auth
niia daemon status
niia daemon gate status --json
niia devices list
niia remote status list
niia remote exec <machine> now
niia remote sessions <machine>
niia remote ask <machine> "hostname"
niia remote update <machine> niia --dry-run
niia mailbox list
niia logout

Surface	Contract
`niia remote exec`	Exact diagnostics only: `now`, `status`, or `--version`
`niia remote ask` / relay write-read	Interactive terminal work after reachability succeeds
`niia remote cp`	File transfer through one exact Headless WebRTC session
`niia daemon gate status`	Read the exact device’s high-risk `exec` and `upgrade` capability state
`niia daemon gate enable` / `niia daemon gate disable`	Mutate one target-device command gate; remote update application requires `upgrade`
`niia remote update`	Plan or apply an exact named tool scope or `--all`; `--dry-run` returns `openclis.update-plan.v1` without mutation
`niia remote upgrade`	Compatibility alias for updating NIIA only, never every tool
`niia remote cleanup --dry-run`	Prints a target-local cleanup plan; it does not widen gateway execution

Do not use diagnostic exec as a general remote shell. That restriction is an intentional security boundary.

Monogram owns deep code intelligence.
Kernel CLI owns native OS observation and action bodies.
MonoSurf owns CDP-visible web-page automation.
Security model explains the gates shared by these surfaces.

​Commands

​Surface counts

​Install and identity

​All 62 top-level commands

​Memory, intelligence, and configuration

​MCP

​Terminal sessions and automation

​OS, transport, and identity

​Work-entry self-drive

​niia gauge [OPTIONS] [TASK]...

​niia finish [--session <id>]

​niia audit-entry [--session <id>] [--hook]

​niia doctor

​Search, index, and analysis

​Document commands

​Code commands

​Git commands

​Session commands

​Consciousness and Monograph

​Skill reconciliation

​MCP commands

​MCP service to CLI

​CLI to MCP

​Persistent sessions

​Terminal driving

​Assertions and scenarios

​Scheduling and pipelines

​Observe commands

​Control commands

​Remote and transport

​Related tools

Commands

Surface counts

Install and identity

All 62 top-level commands

Memory, intelligence, and configuration

MCP

Terminal sessions and automation

OS, transport, and identity

Work-entry self-drive

`niia gauge [OPTIONS] [TASK]...`

`niia finish [--session <id>]`

`niia audit-entry [--session <id>] [--hook]`

`niia doctor`

Search, index, and analysis

Document commands

Code commands

Git commands

Session commands

Consciousness and Monograph

Skill reconciliation

MCP commands

MCP service to CLI

CLI to MCP

Persistent sessions

Terminal driving

Assertions and scenarios

Scheduling and pipelines

Observe commands

Control commands

Remote and transport

Related tools