torii-cli

OpenAPI-driven CLI for the Torii API. Dynamically generates commands from Torii's OpenAPI spec — built for LLM agents and automation.

Prerequisites

You need a Torii account with API access:

1. Log in to your Torii dashboard
2. Go to Settings → API to generate an API key
3. Your API base URL is https://api.toriihq.com

See the Torii API documentation for full details.

Installation

npm install -g torii-cli

Or run directly with npx:

npx torii-cli discovery

Quick Start

# Set your API key (only required credential)
export TORII_API_KEY="your-api-key"

# Verify connection
torii-cli whoami

# Discover all available commands
torii-cli discovery

# List your applications
torii-cli apps list --size 10

To persist credentials, add the export line to your shell profile (~/.bashrc, ~/.zshenv, etc.).

Configuration

| Variable | CLI Flag | Description | |----------|----------|-------------| | TORII_API_KEY | --api-key | API Bearer token (required) | | TORII_API_URL | --api-url | API base URL (defaults to https://api.toriihq.com) | | TORII_SPEC_URL | — | Custom OpenAPI spec URL (optional, defaults to Torii's public spec) |

Usage

# List available commands (fetched from OpenAPI spec)
torii-cli discovery

# Show parameters for a command (types, enums, descriptions)
torii-cli schema apps list

# List applications
torii-cli apps list --size 10

# Get a specific app
torii-cli apps get --idApp <id>

# Auto-paginate all results
torii-cli apps list --page-all

# Preview request without executing
torii-cli apps list --dry-run

# Upload a file
torii-cli files upload --file ./report.csv --type expenseReport

# Download a file
torii-cli files download --id 42 --output ./downloaded.csv

# Filter (for routes supporting custom fields)
torii-cli apps list --filter "state=discovered"

Output Format

All commands output structured JSON to stdout, making it easy to pipe into jq, scripts, or LLM agents:

// Success
{ "data": { ... }, "status": 200 }

// Paginated
{ "data": [...], "status": 200, "pages": 3, "total": 150 }

// Error
{ "error": "Unauthorized", "message": "Invalid API key", "status": 401 }

// Rate limited
{ "error": "Too Many Requests", "status": 429, "retryAfter": 30 }

// Dry run
{ "dryRun": true, "method": "GET", "url": "...", "headers": { ... } }

Built-in Commands

| Command | Description | |---------|-------------| | discovery | List all available API commands as JSON | | schema <group> <action> | Show parameters, types, and enums for a command | | whoami | Show current API environment and connected organization | | version | Show CLI version | | cache clear | Clear the cached OpenAPI spec |

Global Options

| Option | Default | Description | |--------|---------|-------------| | --api-url <url> | $TORII_API_URL | API base URL | | --api-key <key> | $TORII_API_KEY | Bearer token | | --timeout <ms> | 30000 | Request timeout | | --page-all | — | Auto-follow pagination | | --page-limit <n> | 100 | Max pages with --page-all | | --page-delay <ms> | 0 | Delay between pages | | --dry-run | — | Preview request without executing | | --no-cache | — | Skip spec cache and fetch fresh |

For LLM Agents

This CLI is designed for machine consumption. The self-discovery workflow:

# 1. Discover all commands
torii-cli discovery | jq '.data[] | {group, action, kind}'

# 2. Get parameter schema for a specific command
torii-cli schema apps list | jq '.data.parameters'

# 3. Execute with structured output
torii-cli apps list --size 5 | jq '.data'

All output goes to stdout as JSON. Errors and warnings go to stderr. Exit codes: 0 = success, 1 = API error, 2 = client error.

Development

git clone https://github.com/toriihq/torii-cli.git
cd torii-cli
npm install
npm run build     # Compile TypeScript
npm test          # Run tests (50 tests across 6 suites)
npm run lint      # Run biome

Architecture

The CLI fetches Torii's OpenAPI spec at runtime (cached 24h), parses it into operations, builds a commander.js command tree dynamically, executes HTTP requests with Bearer auth, and outputs JSON envelopes to stdout.

bin/torii-cli → src/index.ts → spec.ts (fetch + parse OpenAPI spec)
                             → commands.ts (build commander.js tree)
                             → client.ts (HTTP + pagination + upload/download)
                             → output.ts (JSON envelope formatting)
                             → cache.ts (24h file cache with stale fallback)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT