Doc-301Local CLI

Scan agent artifacts before commit.

The OTONOMI CLI scans MCP configuration, agent manifests, and prompt templates locally. The default mode makes no network request and is suitable for developer machines and CI.

1.0

Install

The CLI is a native binary (Rust) — no Node runtime at scan time. The npm package downloads the prebuilt binary for your platform (Windows x64, macOS x64/arm64, Linux x64/arm64) on install; Cargo builds from source.

Terminal

# one-off
npx otonomi scan .

# global
npm install -g otonomi

# via Cargo
cargo install otonomi

Until the first release is published to npm and crates.io, build from source with a Rust toolchain (about 40 seconds):

Build from source

cargo install --git https://github.com/Moisekenge/otonmi-v2 otonomi
otonomi --version

2.0

Run

Terminal

otonomi scan .

# JSON output for CI
otonomi scan . --json

# Fail only for high or critical findings
otonomi scan . --fail-on high

# Hosted inspection mode (after otonomi login)
otonomi scan . --api

3.0

Authentication

Local scanning needs no account. For hosted mode, create a key in the dashboard (Settings → API Keys), then run otonomi login and paste it. The CLI verifies the key against the API and stores it in your OS credential store — Windows Credential Manager, macOS Keychain, or Linux Secret Service — never a plaintext dotfile. otonomi logout removes it.

Terminal

otonomi login          # paste oton_sk_..., verified + stored in the OS keychain
otonomi scan . --api   # inspect with the hosted engine
otonomi logout         # remove the stored key

Key resolution precedence: --api-key flag → OTONOMI_API_KEY env var → stored credential. In CI, prefer the env var.

4.0

Flags & environment

Flag	Effect
--json	Machine-readable report instead of the table
--fail-on <sev>	Exit non-zero at this severity or above: critical \| high \| medium \| low \| info \| none (default: low)
--api	Inspect with the hosted engine instead of local rules
--api-key <key>	API key for hosted mode (overrides env + stored credential)
--base-url <url>	Alternate hosted engine or test URL
--no-verify	Skip the key check during login
--no-color	Disable ANSI colors (also honors the NO_COLOR env var)
-v, --version / -h, --help	Version / usage

Environment: OTONOMI_API_KEY (hosted-mode key), OTONOMI_BASE_URL (default engine URL — same effect as --base-url), NO_COLOR.

5.0

What it scans

Discovery is curated to agent artifacts — it does not walk your whole repo. Up to 2,000 files, 512 KB each; node_modules, .git, build output, and similar directories are skipped.

MCP configs:mcp.json, .mcp.json, mcp.config.json, claude_desktop_config.json, servers.json, cline_mcp_settings.json
Agent configs:agent.json, agents.json, *.agent.json / *.agent.yaml
Editor rules:.cursorrules, .clinerules, .windsurfrules, .roomodes, .aider.conf.yml
Prompt templates:*.prompt, *.prompt.md/.txt/.yaml, *.tmpl, *.hbs, *.jinja / *.j2
System prompts:system-prompt.*, system.*, prompt.* (md/txt/json/yaml)
Anything text-like inside prompts/, agents/, .mcp/, system-prompts/, .claude/

Detections cover prompt injection, tool poisoning, excessive agency, data exfiltration, supply-chain risk, and embedded secrets — 26 pattern rules plus structural checks over parsed MCP/agent JSON, mapped to the OWASP Top 10 for LLM Applications.

6.0

Exit codes

0 — no finding met the configured threshold.
1 — a finding met or exceeded --fail-on (LOW by default).
2 — invalid arguments, configuration, or transport failure.

7.0

CI example

Workflow step

- name: Scan AI agent artifacts
  run: npx otonomi scan . --fail-on high --json

# The step fails for HIGH or CRITICAL findings.

8.0

Privacy

Local mode does not upload repository files. Secret evidence is redacted in console and JSON output. Hosted mode is opt-in and sends each selected artifact to the inspection endpoint; the service stores aggregate telemetry, not raw artifact content.