Quick start

From a clean shell to a passing fitness run. The point of this page is to give you something working in your terminal before you read the conceptual material — every other doc in this set is sharper once you've seen the output once.

What you'll have after this page:

- The opensip-cli CLI installed.

- A first analysis run, either before initialization or after scaffolding.

- An opensip-cli.config.yml and an opensip-cli/ directory when you choose to initialize.

- One passing fit run, plus an optional sim smoke test.

- A local HTML report and optional paths for agent/MCP access and scanner adapters.

- Enough mechanical context that ./01-what-is-opensip-cli.md lands as "oh, that's why" instead of "wait, what's a recipe?"

Works with

opensip-cli auto-detects your project's language(s) from filesystem markers and runs the matching checks. Polyglot projects get every relevant pack.

| Language | Detection marker | Language-specific checks | Universal checks |

|---|---|---|---|

| TypeScript / JS / TSX | tsconfig.json (or package.json alone) | 58 | ✓ |

| Python | pyproject.toml, setup.py | 2 | ✓ |

| Java | pom.xml, build.gradle | 1 | ✓ |

| Go | go.mod | 1 | ✓ |

| C / C++ | CMakeLists.txt | 1 (clang-tidy backed) | ✓ |

| Rust | Cargo.toml | 1 | ✓ |

Every detected language gets the 96 universal checks (Docker, .env, Sentry, generic structure, dead-code, package conventions). TypeScript additionally gets the deepest treatment through 58 TypeScript-specific checks for typed-inject, drizzle-orm, React patterns, package.json exports, and tsconfig posture.

For the full per-language breakdown, see ../70-reference/02-package-catalog.md.

Prerequisites

Qualified support is narrower than the Node engine range: it names an exact host tuple (OS, architecture, Node ABI, npm major, and filesystem) with measured evidence. The generated supported-platforms matrix is authoritative for each host's current status. Unlisted hosts are unqualified — they may work, with no promise, and the CLI never blocks them.

If you don't have a project handy, git clone https://github.com/opensip-ai/opensip-cli.git and run these commands inside the clone — OpenSIP CLI runs checks against its own codebase as the smoke test.

The first run

# 1. Install the CLI globally
curl -fsSL https://opensip.ai/cli/install.sh | bash

# 2. Enter your project
cd your-project

# 3. Review changed code before writing project files
opensip audit

# 4. Scaffold config + example check/scenario (language auto-detected)
opensip init

# 5. Run the fitness smoke test
opensip fit --recipe example

# 6. Optional: run the scaffolded simulation smoke test
opensip sim --recipe example

fit, graph, graph impact, audit, report, status, runs,

sessions, and project-scoped mcp work in supported projects before

init. In a git repo, audit is changed-scope by default and

prints the resolved scope; pass --full for a whole-repo run. The CLI uses a

validated in-memory config and stores generated runtime state in a managed

user cache. That cache is file-backed and survives normal command exits and

reboots, but it is retention-managed and can be evicted; it is not permanent

history. Direct sim and standalone yagni still require Init.

Inspect retained evidence with opensip status, opensip runs list|show, and

opensip sessions list|show. Agents can attach opensip mcp before Init —

the server uses the same host-selected cache store and holds a shared runtime

lease for the lifetime of the stdio process (Init/removal may report busy until

the client disconnects). Re-open an exact Change Impact report with

opensip report --run <run-id> (run-addressed under reports/runs/; missing

or pruned ids fail closed rather than falling back to “latest”).

opensip init is a transition command, not a storage location. It changes the

project state from zero-config project to initialized project: it writes

the config, examples, .gitignore, and agent guidance into the project,

transactionally adopts retained cache evidence into opensip-cli/.runtime/,

and subsequent local runtime state belongs under that project runtime.

For a human review with the stored Change Impact report, run `opensip audit

--open. For CI or an agent, run opensip audit --json`; JSON, CI, non-TTY, and

remote-shell execution never opens a browser. Initialization is customization

after first value, not a prerequisite for the built-in audit.

If fit --recipe example exits 0, the platform is wired correctly end-to-end: language detection picked the right adapter, the plugin loader found the example check, the recipe service matched it, the engine executed it, and the renderer drew the result. Every later doc is depth on one of those steps.

opensip-cli publishes through npm trusted publishing/provenance and rejects

OpenSIP package-level install hooks before release. For the remaining

npm-install risk model, see supply-chain security.

What init just wrote

your-project/
├── opensip-cli.config.yml                ← project config
└── opensip-cli/
    ├── fit/
    │   ├── checks/example-check.mjs        ← demo check (scope matches your language)
    │   └── recipes/example-recipe.mjs      ← runs the demo check
    └── sim/
        ├── scenarios/example-scenario.mjs  ← demo scenario
        └── recipes/example-recipe.mjs      ← runs the demo scenario

After initialization, opensip-cli.config.yml is the only persisted project

configuration file the CLI requires. Commands eligible before initialization use

a synthesized in-memory configuration instead. Recognized authored files under

opensip-cli/—fit checks and recipes, sim scenarios and recipes, and Tool

sidecars—are discovered at runtime with no extra opt-in. The .runtime/

subdirectory is generated state, not plugin source. opensip init appends

opensip-cli/.runtime/ to your .gitignore so that state does not pollute

commits.

For a polyglot project (for example, Rust + TypeScript), automatic detection

reports the detected set and requires an explicit language list. Run `opensip

init --language rust,typescript`; Init then writes one example check per selected

language.

Variations

# Install from source (for contributors)
git clone https://github.com/opensip-ai/opensip-cli.git
cd opensip-cli && pnpm i && pnpm build
node packages/cli/dist/index.js fit

# Run the default recipe (every enabled check, not just the example)
opensip fit

# See what checks are available
opensip fit list

# See the named fit recipes
opensip fit recipes

# See what graph would analyze without building a catalog
opensip graph --list-files

# Run changed-scope fit + graph evidence in one canonical host-owned review
opensip audit --json

# Open the same run's stored Change Impact evidence for a human
opensip audit --open

# Prepare before-edit task context for agents (explicit files; no findings)
opensip suite run agent-context --files src/server.ts --json

# Ask graph which symbols are impacted by your current git diff
opensip graph impact --changed --json --top 20

# Get a per-violation breakdown instead of the summary line
opensip fit --verbose

# Emit structured JSON for CI
opensip fit --json

# Run the static call-graph tool (different question shape: "what is reachable from where?")
opensip graph

# Open the self-contained local HTML report
opensip report

# Show coding agents the supported machine surfaces
opensip agent-catalog --json

The full command tree is at ../70-reference/01-cli-commands.md.

Configured suites remain available through opensip suite run <name>. The

suite name audit is reserved for the built-in workflow: a configured

suites.audit fails config validation with a rename hint, so opensip audit

and opensip suite run audit always mean the same curated review.

Optional: add a local security scanner

If your team already uses scanners such as Gitleaks, Semgrep, Ruff,

golangci-lint, cargo-deny, Bandit, pip-audit, cargo-clippy, SpotBugs, PMD,

Dependency-Check, Cppcheck, OSV-Scanner, or Trivy, install only the adapter you

want. OpenSIP ships 16 first-party adapter packages, but none are bundled into a

default run. The adapter does not install the scanner binary; doctor checks

that the local binary and cache prerequisites are ready.

# Example: committed-secret scanning with a local gitleaks binary
brew install gitleaks
opensip tools install @opensip-cli/tool-gitleaks
opensip gitleaks doctor
opensip gitleaks

The run lands in the same session store, HTML report, JSON envelope, and

baseline gate path as built-in tools. See

External tool adapters.

If something didn't work

| Symptom | Likely cause | Fix |

|---|---|---|

| Behavior doesn't match what these docs describe | Older CLI version than the docs you're reading | Check installed version: opensip --version (or -V). Latest is on npm. Update with curl -fsSL https://opensip.ai/cli/install.sh \| bash. |

| command not found: opensip-cli | The shell has not picked up the global command yet | Open a new shell and try again; if it still fails, rerun curl -fsSL https://opensip.ai/cli/install.sh \| bash |

| init says it detected no language | No supported language marker found (no package.json, Cargo.toml, etc.) | Pass --language <name> explicitly: opensip init --language typescript |

| fit --recipe example says "0 checks ran" | Targets in opensip-cli.config.yml don't match any files | Open the config; widen targets.<your-language>-source.include to cover where your code actually lives |

| Errors from Node.js engine | Node version is below 24 | Upgrade Node — opensip-cli uses ES2022 + Node16 module resolution |

What's next

You've seen the loop run. The rest of this section deepens what you just saw:

After this section, the mental-model section (../10-concepts/) takes you deep — starting with 01-fitness-loop.md, which threads one check end-to-end through the system you just ran.

Once you've internalized the fitness loop, the tool-specific sections — ../20-fit/, ../30-sim/, and ../40-graph/ — go deep on each first-party tool's pipeline, primitives, and gating model.