Terminal CLI

A CLI for the Terminal Telematics API.

Note: This CLI is still experimental and we may change the command structure or naming before a 1.0 release.

Installation

# Install globally from npm
npm install -g @terminal-api/cli
# or
pnpm add -g @terminal-api/cli
# or
bun install -g @terminal-api/cli

Quick Start

After installing, configure your API key:

terminal config set api-key sk_prod_xxx

Now you can make API calls or start the interactive TUI:

API Calls

terminal list-connections --format table

Interactive TUI

terminal

Run terminal without arguments to launch the interactive terminal UI for browsing and executing API commands.

Configuration

Set your API credentials:

terminal config set api-key sk_prod_xxx
terminal config set connection-token con_tkn_xxx
terminal config set base-url https://api.withterminal.com/tsp/v1

Or use environment variables:

export TERMINAL_API_KEY=sk_prod_xxx
export TERMINAL_CONNECTION_TOKEN=con_tkn_xxx
export TERMINAL_BASE_URL=https://api.withterminal.com/tsp/v1

View current config:

terminal config show
terminal config path

Profiles

Manage multiple configurations with profiles:

# Create a profile
terminal profile create sandbox
# Set values for a profile
terminal config set api-key sk_sandbox_xxx --profile sandbox
terminal config set environment sandbox --profile sandbox
# Use a profile
terminal list-vehicles --profile sandbox
# Set default profile
terminal profile use sandbox
# List all profiles
terminal profile list

Usage

terminal <command> [options]

Global Options

Option	Description
--format <format>	Output format: json, pretty, table (default: json)
--api-key <key>	API key override
--connection-token <token>	Connection token override
--profile <name>	Use a specific config profile
--all	Auto-paginate and fetch all results
--help, -h	Show help
--version, -v	Show version

Examples

# List vehicles with table output
terminal list-vehicles --format table
# Get a specific vehicle
terminal get-vehicle --id vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
# List all drivers (auto-paginate)
terminal list-drivers --all
# List providers (no connection token required)
terminal list-providers
# Get current connection details
terminal get-current-connection --format pretty
# View response schema for a command
terminal list-vehicles schema

Available Commands

Run terminal --help to see all available commands, organized by category:

• authentication - Token exchange
• connections - Manage connections
• data-management - Sync history, passthrough requests
• devices - List devices
• drivers - List/get drivers
• fault-codes - Fault code events
• groups - List groups
• hours-of-service - HOS logs and available time
• ifta - IFTA summaries
• issues - List/resolve issues
• providers - List providers
• safety - Safety events and camera media
• trailers - Trailers and locations
• trips - Historical trips
• vehicle-utilization - Utilization metrics
• vehicles - Vehicles, locations, and stats

Shell Completions

# Bash - add to ~/.bashrceval"$(terminal completions bash)"# Zsh - add to ~/.zshrceval"$(terminal completions zsh)"# Fish
terminal completions fish >~/.config/fish/completions/terminal.fish

AI Agent Skills & Commands

The ai/ folder contains ready-to-use skills and commands for AI coding assistants. These help you query Terminal API data using natural language.

Tool	Type	Install Command
Cursor	Command	cp -r ai/cursor/commands .cursor/commands
Claude Code	Skill	cp -r ai/claude-code/skills .claude/skills
OpenCode	Skill	cp -r ai/opencode/skill .opencode/skill

Example queries:

• "How many safety events for driver X this week?"
• "Where was vehicle ABC on January 2nd?"
• "Which vehicles have active movement?"

See ai/README.md for full setup instructions.

Development

# Run CLI in dev mode (with watch)
bun run dev
# Regenerate commands from OpenAPI spec
bun run generate
# Run all checks (typecheck, lint, format, test)
bun run check
# Individual checks
bun run typecheck
bun run lint
bun run format
bun test# Build
bun run build
# Install dependencies for VS Code/etc.
bun install
# Link to use globally
bun link

Architecture

The CLI is primarily driven by the OpenAPI spec at https://api.withterminal.com/tsp/openapi:

src/
cli.ts # Main CLI entrypoint
lib/
client.ts # HTTP client with auth
config.ts # Config management (~/.terminal/config.json)
output.ts # Output formatting
completions.ts # Shell completion generators
tui/ # Interactive terminal UI
scripts/
generate.ts # OpenAPI spec parser & code generator
generated/ # Auto-generated command files
index.ts
vehicles.ts
drivers.ts
...

To add new commands, update the OpenAPI spec and run bun run generate.