CLI Scanner

The Routemage CLI scans your Next.js, Express, Fastify, or NestJS project, generates a manifest of every endpoint, and auto-uploads it to your workspace in one command. No file shuffling required.

Supported Frameworks

The CLI auto-detects which framework(s) your project uses based on package.json and the file layout. Multi-framework monorepos are fully supported — every framework with matching files contributes endpoints to a single manifest.

FrameworkDiscoveryBest signal for body
Next.js (App Router)app/**/route.tsZod schemas, type annotations, req.json() destructure, formData()
Next.js (Pages Router)pages/api/**/*.tsreq.body accesses, Request<P,R,B> generics, Zod
Expressapp.METHOD() + Router() with mount-prefix tracingreq.body accesses, Request<P,R,B> generics, Zod
Fastifyfastify.METHOD() / fastify.route() + register({ prefix })JSON Schema in opts.schema.body — gold standard
NestJS@Controller + @Get/@Post/etc. decorators@Body() dto: SomeDto resolved via class-validator + @ApiProperty

Installation

No install required for one-off use. Run the latest version with npx:

Terminal
npx routemage --version

Or install globally to skip the npx prefix on every run:

Terminal
npm install -g routemage
# or
pnpm add -g routemage

Logging In

Before the CLI can upload manifests, it needs your API key. Run routemage login once — you only ever need to do this once per machine.

Terminal
routemage login

The CLI will prompt you to paste your API key and verify it against the app. On success, the key is saved to ~/.routemage/config.json.

Example output
routemage login
Get your API key at https://app.routemage.com/settings/api-keys

Paste your API key: rx_live_••••••••••••
✓ Logged in as you@example.com
Key saved to ~/.routemage/config.json

Now run: routemage scan
Info
Your API key is always available in the Settings panel of the web app — open the sidebar and click Settings.

API key priority. When the CLI needs a key, it checks these locations in order — first match wins:

  • ROUTEMAGE_API_KEY environment variable — highest priority, ideal for CI/CD
  • ~/.routemage/config.json — set by routemage login
  • .routemage.config.json in the project root — optional team-shared key

Scanning a Project

Run the scan command from the root of your project. After login, this uploads automatically:

Terminal
# Scan current directory (auto-uploads)
routemage scan

# Scan a specific path
routemage scan ./my-app

The CLI detects which frameworks your project uses, walks the relevant directories (app/, pages/api/, controller files, route files), and analyses each one with TypeScript AST parsing — including cross-file type resolution for DTOs and shared schemas.

Info
Your project does not need to be running. The CLI reads source files — it does not make HTTP requests or start a server.

Understanding the Output

The CLI prints a summary table to your terminal and writes routemage/manifest.json locally before uploading:

Terminal output example
✔ Detected 1 framework: nextjs-app
✔ Scanned 22 endpoints

GET     /api/users                        [high] (nextjs-app)
POST    /api/users                        [high] (nextjs-app)
GET     /api/users/:id                    [high] (nextjs-app)
PUT     /api/users/:id                    [medium] (nextjs-app)
DELETE  /api/users/:id                    [high] (nextjs-app)
GET     /api/posts                        [high] (nextjs-app)
POST    /api/posts                        [medium] (nextjs-app)

✓ 22 endpoints synced → app.routemage.com/w/my-project

Each endpoint entry includes:

FieldDescription
methodHTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
pathRoute path with :param notation for dynamic segments
params.pathPath parameters extracted from the route pattern
params.queryQuery parameters detected from searchParams.get() calls
bodyBody fields detected from Zod schemas or destructured req.json()
authAuth pattern detected (Bearer, Basic, API Key, session)
confidencehigh | medium | low — how certain the extractor is

Auto-Upload

After a successful login, routemage scan uploads automatically every time. There is no separate upload step. The workspace URL is printed at the end of each scan.

If no API key is found, the CLI writes the manifest locally and prints instructions to run routemage login. No upload happens, but your local manifest is still available.

Tip
In CI, set ROUTEMAGE_API_KEY as a secret environment variable. No routemage login step is needed.
.github/workflows/routemage.yml
- name: Scan and upload API manifest
  run: npx routemage scan
  env:
    ROUTEMAGE_API_KEY: ${{ secrets.ROUTEMAGE_API_KEY }}

Scan Flags

FlagDescription
routemage scanScan + auto-upload to your workspace (default)
routemage scan --output manifest.jsonScan and write manifest to a specific path — no upload
routemage scan --no-uploadScan and write to routemage/manifest.json — no upload
routemage scan --generate-docsAfter upload, trigger AI doc generation for all routes (async, non-blocking)

The --output and --no-upload flags are useful for air-gapped environments or when you want to inspect the manifest before sending it. The resulting JSON file can be imported manually via the Import button in the web app sidebar.

The --generate-docs flag triggers a background AI job that generates documentation for every route. The CLI exits immediately — you'll receive an email when generation finishes.

Getting Your API Key

Your API key is available in the web app. Open the Settings panel from the bottom of the sidebar. Your key is shown there and can be copied or rotated at any time.

  • Rotating a key immediately invalidates the old one — update CI secrets and re-run routemage login on any affected machines
  • Never commit your API key to version control — use environment variables or a secret manager

Logging Out

To remove the saved API key from your machine:

Terminal
routemage logout

This clears ~/.routemage/config.json. The next routemage scan will print instructions to log in again, or will use ROUTEMAGE_API_KEY if set.