@suss/cli

Read a codebase and check what it does at every boundary, such as a route or a table, against the clients, specs and infrastructure on the other side. It works on TypeScript, Python and Ruby.

This package is the command line for suss. It gives the same output every time for the same code, and it does not use a model.

Read one service

npx @suss/cli extract -f hono -o api.json
npx @suss/cli inspect api.json

src/api.ts
├─ GET /users/{id}  (hono handler | line 5)
│      if  !findUser()
│        -> 404 { error }
│      elif  findUser().deletedAt
│        -> 410 { error }
│      else
│        -> 200 { id, name, email }
│
└─ POST /users  (hono handler | line 19)
       if  !c.req.json().name
         -> 400 "name is required"
       else
         -> 201 { id, name }

The output lists every path each handler can take, with the status and the body fields it produces. When suss could not follow a call, it reports that under the handler and keeps the path in the list.

Install

npm install --save-dev @suss/cli

Every pack ships inside the CLI, so -f hono and -f rails need nothing else installed. suss init reads your dependencies and writes out the commands for your own project.

The four commands

| Command | What it does | |---|---| | suss init | Reads the project and prints the commands to run, or walks you through them | | suss extract | Reads code into summaries, one pack per framework, client or ORM | | suss contract | Reads a declared artifact, an OpenAPI document or a SAM template, into the same summaries | | suss check | Compares every provider against every consumer and reports where the two disagree |

Two more commands read what is already on disk. suss inspect renders summaries, including --diff between two runs and --flow for one request hop by hop, and suss ask answers one question about one boundary.

The CLI reference covers every command and flag.

In a coding agent

Your agent reaches the same summaries over MCP, so it can ask what a route reaches or what writes a table before it edits either:

{
  "mcpServers": {
    "suss": { "command": "npx", "args": ["-y", "@suss/mcp", "/path/to/project"] }
  }
}

The package ships its own AGENTS.md, at node_modules/@suss/cli/AGENTS.md, so an agent working from an installed copy has the same guide the repository shows.

More

• Documentation
• Add suss to a project
• Every pack suss ships
• What init reads before it suggests anything
• Source and issues

Apache 2.0. See LICENSE.