> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # NIIA Commands > Complete NIIA 0.9.50 command map — self-drive modes, memory, intelligence, sessions, MCP, OS control, automation, and remote transport. # Commands This reference documents **NIIA 0.9.50**, 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 four published platform fragments carry the current command and guide surface. ## Surface counts | Surface | Count | Contract | | -------------------- | ----: | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Top-level CLI | 63 | The human and shell entry points below; generated `help` is additional | | Generated MCP schema | 109 | Supported non-recursive commands, including `niia_mode`, `niia_docs_topic`, and `niia_docs_guide`, with nested groups flattened into typed tools | | Live `niia mcp` | 110 | Generated tools plus the running server's self-status surface | 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](/ai-clis/niia#release-provenance-and-platform-matrix) for immutable platform and payload proof. ## Install and identity ```bash theme={null} openclis install niia openclis update niia niia --version niia status ``` ## All 63 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 mode` | Switch between automatic hook steering and manual invocation, inspect routing, or deploy a named preset | | `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 | ## Self-drive mode and presets ```text theme={null} AUTO prompts ── hooks ──▶ gauge ──▶ witness ──▶ finish ──▶ audit MANUAL no NIIA hooks; you invoke the same verbs when judgment requires them routing preset: default = balanced strict = announce every rung quiet = keep witness/audit, minimize injection ``` ```bash theme={null} niia mode niia mode auto niia mode manual niia mode routing niia mode preset niia mode preset default|strict|quiet ``` The default scope is the current project's settings; `--user` selects the user-level settings. `auto` adds exactly the three NIIA hooks, while `manual` removes exactly those hooks. Both preserve foreign hooks and unrelated settings. `on` and `off` are aliases for `auto` and `manual`. Deploying a preset backs up a custom routing table before replacement. ## 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. ```bash theme={null} 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 ` records an `ESCALATE` or `DE-ESCALATE` history event, and `--session ` selects the witness explicitly. `--transcript ` 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 `/.niia/session-order//`; outside Git they live under `~/.niia/session-order///`. 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 ]` `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 [OPTIONS]` 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. `--transcript ` supplies a transcript collected after the session ended. `--no-witness --transcript --assume-rung --cwd ` audits a baseline run that never called `gauge`: behavioral classes are checked, contract-only classes are skipped, and the report discloses the assumed rung. Use `--wide-evidence` on both arms of a comparison or neither arm. 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 ```bash theme={null} 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 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. ```bash theme={null} 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 ` | Read one of 14 embedded NIIA flow topics; bare `niia docs` lists the catalog | | `niia docs guide ` | Compatibility alias for the embedded topic reader | | `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 | ```bash theme={null} niia docs self-drive niia docs install-trust 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](/ai-clis/monogram/reference) 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 | ```bash theme={null} 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 | ```bash theme={null} niia session list --tool codex -n 5 niia session read latest --tool grok --full niia session search "release boundary" -n 10 ``` See [AI sessions](/niia-cli/sessions) for the provider and PTY boundaries. ## Consciousness and Monograph ```bash theme={null} 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 | ```bash theme={null} 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.50 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: ```powershell theme={null} & "$HOME\.openclis\bin\niia.exe" setup use openclis where.exe niia niia --version ``` ## MCP commands ### MCP service to CLI ```bash theme={null} 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:` for service/schema help. `--help` is the NIIA command's own Clap help and is not a wrapped tool lookup. ### CLI to MCP ```bash theme={null} niia mcp niia --mcp-schema niia mcp-serve monogram niia mcp-serve ``` The generic bridge uses ` --mcp-schema` when present; otherwise it exposes one passthrough tool returning the CLI's raw output. ### Persistent sessions ```bash theme={null} 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 ```bash theme={null} niia health --session niia write --session $'claude\r' niia wait-idle --session niia get-answer --session "your exact prompt" niia ask --session "run the focused tests" niia follow-up --session "summarize failures" --expect-last "tests" ``` Use `\r`, not `\n`, as Enter for raw-mode terminal applications. ### Assertions and scenarios ```bash theme={null} niia expect-screen --session "Finished" --show niia expect-history --session "Finished" --tail 100 --show niia expect-system --cli codex --transcript "done" niia step --session --send "cargo check" --expect "Finished" --read screen niia scenario --session ``` 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 ```bash theme={null} niia auto --session --every 5m --run "cargo check" --times 3 --log niia auto --new --where --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](/kernel-cli/commands) can pass through `niia observe`. NIIA rejects write commands on this entrance. ## Control commands ```bash theme={null} 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: ```bash theme={null} niia login niia auth niia daemon status niia daemon gate status --json niia devices list niia remote status list niia remote exec now niia remote sessions niia remote ask "hostname" niia remote update 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. ## Related tools * [Monogram](/ai-clis/monogram/overview) owns deep code intelligence. * [Kernel CLI](/kernel-cli) owns native OS observation and action bodies. * [MonoSurf](/monosurf/index) owns CDP-visible web-page automation. * [Security model](/niia-cli/security) explains the gates shared by these surfaces.