CLI

The SecondOS CLI runs on Bun, with no build step. It syncs your repo into a structure-aware map, answers questions against it, and flags code-to-DB drift.

Install

Run it on demand with npx, or add it to your project:

bunx @secondos/cli push .

push · sync the map

Parses the repo into symbols, signatures, routes and a relationship graph, then uploads the map and embeddings. Re-runs are incremental via a parse cache, so only what changed is re-processed.

secondos push .            # sync the current repo
secondos push . --deep     # also embed symbol bodies (logic search)

With --deep, bodies are read and embedded locally; only the vector and line references persist, never the source text.

Map the codebase — secondos scan

secondos scan turns your repo into a shareable, structure-aware map: the parts, how they connect, which services write which data, and the decisions behind them — built from the map, never your source. Turn on sharing to publish a read-only link. No account needed? Anyone can try it at /scan/try by copying a prompt into their own agent and pasting the output. Add --narrate to rename each part in plain feature language.

secondos scan .            # build the shareable map (upload to your project)
secondos scan . --dry-run  # write .secondos/scan.json, upload nothing
secondos scan . --narrate  # rename the parts in plain feature language (needs model creds)
npx @secondos/scan .       # no install: run the same scan from anywhere

ask · query offline

Ask a question against the synced map. It fuses lexical and semantic retrieval and grounds answers in real symbols and line references.

secondos ask "where do we hash passwords?"

drift · schema, env and deps

Runs three read-only checks: your code against the Drizzle schema, the environment variables your code reads (process.env) against .env.example, and the packages you import against package.json. It reports the undeclared and the likely-unused, with both locations, and changes nothing.

secondos drift            # all three checks; 0 findings on a clean repo

mcp-config · print your editor setup

Prints the ready-to-paste MCP configuration for Cursor, Claude Code, Claude Desktop, Windsurf and VS Code. Copy it into your editor's MCP settings and the SecondOS server is wired up, no hand-writing JSON.

secondos mcp-config       # print config for every supported editor

init-github-action · keep the map fresh

Scaffolds a GitHub Actions workflow that re-extracts changed files on every push and updates the cloud map. It runs in your CI, so your source never leaves your boundary and the map stays fresh without manual re-syncs.

secondos init-github-action   # write .github/workflows/secondos.yml

docs · ship the living knowledge base

Writes the living docs from your map, per-file summaries and accepted memories (the overview, architecture, module, API and data-model docs), never your source bodies (K-S23). It needs model credentials. Add --push to store the byte-identical docs to the cloud, so the web app and the read_living_doc MCP tool serve them.

secondos docs .           # write the living docs from the map
secondos docs . --push     # also store them to the cloud (Pro)

Offline mode

For fully offline runs, set SECONDOS_EMBEDDER=stub and SECONDOS_SUMMARIZER=stub. The map still builds; only the cloud-backed embedding and summary steps are stubbed.

MCP server

The same CLI hosts the MCP server that feeds your editors. See the MCP page for the tools and editor setup, or start from the quickstart.