CLI Commands — paso Docs

paso has five commands: init, validate, inspect, test, and serve.

usepaso init

Scaffold a new usepaso.yaml declaration.

usepaso init --name "ServiceName"

From an OpenAPI spec

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

This generates a usepaso.yaml from your OpenAPI spec. Edit the result to curate capabilities and set permissions.

usepaso validate

Check your declaration for errors.

usepaso validate

Output on success:

valid (ServiceName, N capabilities)

Output on failure:

Error: Missing `capabilities` field in usepaso.yaml.
Every declaration needs at least one capability.

Validation checks:

All required fields are present
Field types are correct
No duplicate capability names
Auth configuration is valid
Path variables match inputs

usepaso inspect

Preview what MCP tools will be generated from your declaration.

usepaso inspect

Output:

Service:  ServiceName
Tools:    N
Protocol: MCP

  list_items       List all items
  create_item      Create a new item
  delete_item      Delete an item by ID

usepaso test

Test a capability with a real HTTP request.

usepaso test <capability> [options]

Options

Flag	Description
`-p <key=value>`	Pass a parameter (repeatable)
`--dry-run`	Preview the request without sending it
`--verbose`	Show full request and response details

Examples

Test a capability:

usepaso test list_items -p limit=5

Test with multiple parameters:

usepaso test create_issue -p owner=acme -p repo=app -p title="Bug report"

Preview without sending:

usepaso test list_items --dry-run

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

GET /items?limit=5
Authorization: Bearer [REDACTED]

Authentication

Set the environment variable your declaration expects:

export USEPASO_AUTH_TOKEN=your-token
usepaso test list_items

usepaso serve

Start an MCP server from your declaration.

usepaso serve

Output:

usepaso serving "ServiceName" (N capabilities)

The server runs on stdio. MCP clients (Claude Desktop, Cursor) connect to it. Stop with Ctrl+C.

Using with npx

npx usepaso serve

This is the recommended approach for Claude Desktop and Cursor configs. No global install needed.

Environment variables

Variable	Description
`USEPASO_AUTH_TOKEN`	Default auth token (used when `auth.type` is `bearer`)
Custom variables	Set any variable your declaration’s `auth.env_var` specifies

Example:

export GITHUB_TOKEN=ghp_xxxxx
usepaso serve

CI/CD

Validate declarations in CI:

# GitHub Actions
- run: npm install usepaso
- run: npx usepaso validate

Next steps

Declaration Spec — full YAML field reference
Testing Capabilities — test workflows in detail
Quick Start — end-to-end walkthrough