FAQ

Common questions. If yours isn't here, the answer probably lives somewhere in the architecture corpus — or open an issue on GitHub.

Is the CLI localized / translated?

No — English only today. Programming-language adapters (lang-typescript,

lang-rust, …) are for parsing source code, not UI localization. Localization

extraction is deferred unless an enterprise contract requires it — see

ADR-0072.

Does opensip-cli "phone home"?

Not for telemetry. Summary by surface (ADR-0070):

--no-cloud or config.

check); silence with OPENSIP_NO_UPDATE=1 or NO_UPDATE_NOTIFIER=1.

telemetry.

Update state stores only { latest } — no user paths or credentials.

Is opensip-cli a linter replacement?

No. ESLint, Ruff, golangci-lint, and clang-tidy still belong in your toolchain — they're sharper at language-specific syntactic patterns. opensip-cli sits above linters: it adds the architectural rules, cross-file constraints, and polyglot gates that linters can't express. You run both in CI.

See vs. other tools for the full comparison.

Do I have to write recipes?

No. The built-in default recipe runs every enabled check. Recipes are useful when you want a named lineup ("quick-smoke for pre-commit, full for nightly") but they're optional. The quick start uses the scaffolded example recipe just to prove the wiring works.

Do I have to use every built-in tool?

No. Each is independent. Most teams adopt fit first (the primary loop), add

graph when they want static call-graph analysis, run yagni when they want an

advisory reduction audit, and only use sim if they have a workload to

simulate. You can run opensip fit and never touch the others.

What is opensip audit vs opensip suite run audit?

The same curated built-in review. Top-level opensip audit is the memorable

host command; opensip suite run audit is the generic suite spelling. Both

share one executor and always use the built-in definition — the suite name

audit is reserved, so a configured suites.audit is rejected. Use

--json for agents/CI and --open for the human Change Impact report. Custom

multi-tool workflows use another suite name (audit-custom, …). See

audit command reference.

How should coding agents prepare before editing?

Record task context, then read it. Run

opensip suite run agent-context --files <path> --json (or trust a prior Run

via MCP get_context_status when readiness checks pass). During the edit use

get_file_context, impact_files, select_tests, and entity-detail

get_symbol. Ordinary MCP reads never rebuild the graph, invoke Git, run tests,

or start the suite. After edits, prefer opensip audit --json for the

finding-oriented review. Full loop:

Use OpenSIP with AI agents.

Does init install scanner adapters for me?

No. A successful pristine init may recommend language-relevant optional

adapters (optionalTools in JSON, a footer in human mode) with the exact

install commands. It never prompts, installs, or runs adapter code. Install

what you want with opensip tools install ….

Is the zero-config cache really ephemeral? Does init make evidence permanent?

No to both. The zero-config cache is persistent-on-disk, retention-managed local

storage. It survives commands and reboots, but its whole project entry can be

automatically removed when the project path disappears, after 30 days without

use, or under the project-count policy. The active entry is protected while the

policy retains up to 50 other survivors. Those are eviction defaults, not an

archival guarantee.

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

project state from zero-config project to initialized project, writes the

project's explicit config and authored guardrails, and makes the gitignored

project .runtime/ authoritative for subsequent local evidence. On a

successful scaffold path, when the cache runtime exists and the project

runtime does not, initialization also moves the existing cache evidence there;

otherwise it leaves both locations intact. Both project states use the same

SQLite and runtime-file formats.

Initialized evidence is not permanent or shared through Git: ordinary session

and artifact retention still applies. What becomes durable and team-portable is

the committed project intent—config, checks, recipes, scenarios, and guidance.

See Session and persistence.

Does it work offline?

Yes. The CLI runs fully offline. Optional --report-to <url> delivery posts

SARIF to an explicitly configured endpoint, and optional OpenSIP Cloud signal

sync is disabled unless an API key and entitlement are configured. The local

report, sessions, JSON, gates, and installed adapter runs work without network

access.

What's OpenSIP Cloud, and do I need it?

OpenSIP Cloud is a separate product (at opensip.ai) that

aggregates CLI evidence across runs. OpenSIP CLI is fully usable without it.

There are two optional network paths:

compatible receiver and can fail a CI build with exit code 4 when upload fails.

and cloud entitlement are configured; disable it with --no-cloud or config.

Can I write checks in TypeScript instead of .mjs?

Yes. When a check pack outgrows a handful of .mjs files, you can promote opensip-cli/fit/ to a workspace npm package: add a package.json declaring opensipTools.kind: "fit-pack", targetDomain: "fit-pack", and targetDomainApiVersion: 1, switch the files to TypeScript, add opensip-cli/* to your workspace globs, run pnpm i. Marker-based discovery picks it up on the next run.

The graduation path is documented in plugin authoring. The .mjs shape is faster for first-touch; the workspace-package shape is better once coverage grows.

How do I adopt opensip-cli incrementally on a large codebase?

Use the baseline gate flow. Run opensip fit --gate-save once to capture every current violation as a baseline. Future CI runs use --gate-compare and fail only on new violations, not on the historical ones. You can fix the baseline over time without blocking PRs from day one.

graph has the same flow (--gate-save / --gate-compare) for catalog drift.

What languages does it support?

fit runs against TypeScript / JavaScript, Python, Rust, Go, Java, and C/C++. Language detection is automatic (looks for tsconfig.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, CMakeLists.txt). Most built-in checks are language-agnostic (the 96-check checks-universal pack); the rest target a specific language pack.

graph ships five language adapters: TypeScript, Python, Rust, Go, Java. The TypeScript adapter uses the TypeScript compiler API; the Python, Go, Rust, and Java adapters parse with vendored web-tree-sitter WASM grammars, so there's no native toolchain or compiler to install for them.

sim is language-independent — scenarios are JavaScript and drive your service over HTTP.

What operating systems / hosts are qualified?

Language support and host support are different questions. The package

engines.node: ">=24" range is an install floor — it does not encode OS,

architecture, Node ABI, npm major, filesystem, or case behavior, and it is not a

support claim. Qualified host support names an exact tuple across those

dimensions with measured evidence, and every host resolves to one of four

statuses: supported (measured, past burn-in, every release evidence-gated),

preview (published with evidence but documented gaps), unqualified (not

measured — may work, no promise), or unsupported (an exact, intentionally

excluded tuple). The exact qualified tuple, the current status of each host,

and the reporting instructions live in the generated, authoritative

supported-platforms matrix — this

page deliberately does not restate the mutable status so the two can't drift.

Agents can read the same registry: opensip agent-catalog --json (and the MCP

get_agent_catalog tool) include a hostSupport block. It is built only from

process-observable facts, so its local match is never exact — partial on a

clean match, none on a contradiction — and agents should read the registry

row's status separately from that local match. To request a host, open a

GitHub issue with your hostSupport block plus node/npm/sw_vers/uname

output as described in the matrix.

Can I run only one check?

Yes. opensip fit --check <slug> runs exactly one check. Useful for debugging a single rule or for pre-commit hooks that want one fast check.

How fast is it?

Typical: a few seconds for a small project, sub-30-seconds for a large one. graph has incremental rebuild (edits to one file rebuild in ~2.5s vs ~15s cold on the opensip-cli self-graph).

The runtime cost scales with checks × matched-files, not with project size. A check with scope: { languages: ['typescript'] } only runs against TypeScript files, even in a polyglot repo. The execution model is parallel by default.

What's the difference between a check, a recipe, a scenario, and a rule?

duplicated-function-body, near-duplicate-function-body, large-function, etc.).

A rule is authored with defineRule, the call-graph parallel to

defineCheck; eleven ship in the box.

The difference from a check is the input: a rule queries the engine

dataset (call graph + derived feature columns), not a single file's

(content, filePath).

See vocabulary for the full glossary.

Can I use security tools I already have, like Gitleaks?

Yes. Install the OpenSIP adapter, keep managing the scanner binary yourself,

and run doctor to confirm the binary and local prerequisites are ready:

opensip tools install @opensip-cli/tool-gitleaks
opensip gitleaks doctor
opensip gitleaks

The shipped opt-in adapters cover Gitleaks, Semgrep, ast-grep, Ruff,

golangci-lint, govulncheck, cargo-deny, Bandit, pip-audit, cargo-clippy,

SpotBugs, PMD, Dependency-Check, Cppcheck, OSV-Scanner, and Trivy. Adapter

findings become normal OpenSIP signals: they appear in sessions, JSON, SARIF,

the HTML report, live CLI progress, and the baseline ratchet. See

External tool adapters.

Is this an AI tool?

Not in the model-runtime sense. opensip-cli does not call models, create

embeddings, or autonomously change your code. It is a plain TypeScript CLI that

emits deterministic evidence.

It is intentionally AI-agent friendly: --json, sessions, agent-catalog,

MCP, agent filters, and agent recipes let external coding agents inspect prior

runs, understand blast radius, and verify their work. The product boundary is:

agents may consume OpenSIP's guardrails; OpenSIP itself is not the agent.

See Use OpenSIP with AI agents,

Connect MCP clients, and

plugin authoring.

How do I report a bug or request a feature?

GitHub issues. Bug reports should include opensip --version, a minimal reproduction, and the run's <runtime-root>/logs/<date>.jsonl file if relevant. The runtime root is in the managed user cache before initialization and project .runtime afterward.

What's next

| If you want to … | Go to … |

|---|---|

| See how opensip-cli compares to alternatives | vs. other tools |

| See concrete code samples | Show me each loop |

| Run the first smoke test | Quick start |

| Browse all built-in checks | Checks reference |