CLI Commands — paso | MCP Server Generator

Reference for all paso CLI commands: init, validate, inspect, test, serve, doctor, connect, disconnect, completion.

usepaso init

Create a usepaso.yaml template in the current directory.

usepaso init
usepaso init --name "Sentry"
usepaso init --from-openapi ./openapi.json
usepaso init --from-openapi https://api.example.com/openapi.json

Flag	Description
`-n, --name <name>`	Service name (default: `MyService`)
`--from-openapi <path>`	Generate from an OpenAPI 3.x spec (JSON, YAML, or URL)

If usepaso.yaml already exists, the command exits with an error.

When using --from-openapi, the CLI prints a summary of generated capabilities and auth type. OpenAPI imports cap at 20 capabilities. See the OpenAPI import guide for a full walkthrough.

usepaso validate

Validate a usepaso.yaml file against the spec.

usepaso validate
usepaso validate -f ./path/to/usepaso.yaml
usepaso validate --strict
usepaso validate --json

Flag	Description
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)
`--strict`	Enable best-practice checks
`--json`	Output result as JSON

Output

valid (Sentry, 6 capabilities, 0 regrets)

Strict Mode

Checks for best practices beyond basic validation:

DELETE capabilities without consent_required
Descriptions shorter than 10 characters
Write/admin capabilities with no constraints
Missing permissions section

JSON Mode

Returns structured output:

{
  "valid": true,
  "service": "Sentry",
  "capabilities": 6,
  "errors": [],
  "warnings": []
}

usepaso inspect

Show what MCP tools would be generated from your declaration.

usepaso inspect
usepaso inspect -f ./usepaso.yaml
usepaso inspect --json

Flag	Description
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)
`--json`	Output result as JSON

Output

Service: Sentry
Tools:   6
Auth:    bearer

  ┌ list_issues (read)
  │ GET /projects/{organization_slug}/{project_slug}/issues/
  │ List issues in a project, optionally filtered by status
  │ params: organization_slug*: string, project_slug*: string, query: string
  │
  └ resolve_issue (write) [consent required]
    PUT /issues/{issue_id}/
    Mark an issue as resolved
    params: issue_id*: string, status*: enum

Capabilities in the forbidden list are excluded from the output.

JSON Mode

Returns structured output with tool details, useful for programmatic inspection.

usepaso test

Test a capability against the live API, or preview the request with --dry-run. See the testing guide for patterns and workflows.

usepaso test <capability> -p key=value
usepaso test <capability> --dry-run
usepaso test --all --dry-run

Flag	Description
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)
`-p, --param <key=value>`	Parameters (repeatable)
`--dry-run`	Show the HTTP request without executing it
`--all`	Test all capabilities (requires `--dry-run`)
`--timeout <seconds>`	Request timeout in seconds (default: `30`)

Single Capability

usepaso test list_issues -p organization_slug=my-org -p project_slug=my-project

Dry Run

usepaso test list_issues -p organization_slug=my-org --dry-run

--- DRY RUN (no request will be made) ---

GET https://sentry.io/api/0/projects/my-org/{project_slug}/issues/
Authorization: Bearer ...

Test All

usepaso test --all --dry-run

ok list_issues     GET https://sentry.io/api/0/projects/{organization_slug}/{project_slug}/issues/
ok resolve_issue   PUT https://sentry.io/api/0/issues/{issue_id}/

2 passed. 2 capabilities total.

Running --all without --dry-run is not supported.

No Capability Specified

Running usepaso test without a capability name lists available capabilities.

usepaso serve

Start an MCP server from a usepaso.yaml declaration.

usepaso serve
usepaso serve -f ./path/to/usepaso.yaml
usepaso serve --verbose
usepaso serve --watch

Flag	Description
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)
`--env <path>`	Path to .env file (default: `.env` next to usepaso.yaml)
`-v, --verbose`	Log all requests to stderr
`-w, --watch`	Notify when usepaso.yaml changes
`--strict`	Enforce consent gates server-side (for headless or untrusted agents)

Output

usepaso serving "Sentry" (6 capabilities). Agents welcome.
Transport: stdio. Waiting for an MCP client...

The command also prints the MCP config snippet for connecting Claude Desktop or Cursor.

Verbose Mode

Logs every request with timestamp, capability name, method, URL, status, and duration:

[14:23:01] list_issues → GET https://sentry.io/api/0/projects/my-org/my-project/issues/ ← 200 (342ms)

Auth tokens are redacted in verbose output.

Watch Mode

Monitors usepaso.yaml for changes and notifies you to restart the server.

Auth Warnings

The serve command warns at startup if:

USEPASO_AUTH_TOKEN is set but empty
Auth is configured but USEPASO_AUTH_TOKEN is not set
base_url uses plain HTTP (tokens sent in cleartext)

usepaso doctor

Check your usepaso setup for common issues. Runs five checks in sequence.

usepaso doctor
usepaso doctor -f ./path/to/usepaso.yaml

Flag	Description
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)
`--env <path>`	Path to .env file (default: `.env` next to usepaso.yaml)

Output

usepaso doctor

  ok   usepaso.yaml found
  ok   YAML parses correctly
  ok   Validation passes (6 capabilities)
  ok   USEPASO_AUTH_TOKEN set
  ok   Base URL reachable (https://sentry.io/api/0, 187ms)

────────────────────────────────────
All checks passed.

Checks

File exists. Is usepaso.yaml present?
YAML parses. Is it valid YAML?
Validation passes. Does it pass all spec validation rules?
Auth token. Is USEPASO_AUTH_TOKEN set (when auth is configured)?
Base URL reachable. Can the SDK reach service.base_url? (5-second timeout)

See Troubleshooting with Doctor for detailed usage.

usepaso connect

Add this server to an MCP client config. paso reads your declaration, builds the correct config entry, and writes the file for you.

usepaso connect <client>
usepaso connect claude-desktop
usepaso connect cursor
usepaso connect vscode
usepaso connect windsurf

Flag	Description
`<client>`	Client to configure: `claude-desktop`, `cursor`, `vscode`, `windsurf`
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)
`--env <path>`	Path to .env file (default: `.env` next to usepaso.yaml)
`--force`	Overwrite existing entry if one already exists for this service

Output

Added "Sentry" in Claude Desktop config.
  Config: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop to connect.

If USEPASO_AUTH_TOKEN is not set, paso prints a warning and adds a placeholder in the config.

If an entry for this service already exists, the command exits with an error. Use --force to overwrite.

usepaso disconnect

Remove this server from an MCP client config.

usepaso disconnect <client>
usepaso disconnect claude-desktop

Flag	Description
`<client>`	Client to update: `claude-desktop`, `cursor`, `vscode`, `windsurf`
`-f, --file <path>`	Path to usepaso.yaml (default: `usepaso.yaml`)

Output

Removed "Sentry" from Claude Desktop config.
  Config: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop to connect.

If the config file does not exist, or no entry is found for this service, the command exits cleanly with no error.

usepaso completion

Output shell completion scripts.

usepaso completion
usepaso completion --shell zsh
usepaso completion --shell fish

Flag	Description
`--shell <shell>`	Shell type: `bash` (default), `zsh`, `fish`

Bash

eval "$(usepaso completion)"

Zsh

eval "$(usepaso completion --shell zsh)"

Fish

usepaso completion --shell fish | source

usepaso version

Print the usepaso version.

usepaso version

Global Flags

These flags work across multiple commands:

Flag	Commands	Description
`-f, --file <path>`	validate, inspect, test, serve, doctor, connect, disconnect	Path to usepaso.yaml

Environment Variables

Variable	Description
`USEPASO_AUTH_TOKEN`	API token used for authentication in `test` and `serve`