CLI Reference

Example CLI Tool Reference

This sample demonstrates CLI documentation: installation, command reference, global options, output formats, and configuration files.

Installation

macOS

# Using Homebrew
brew install example-cli

# Or download directly
curl -fsSL https://get.example.com/cli | sh

Linux

# Debian/Ubuntu
curl -fsSL https://get.example.com/cli/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg
echo "deb [signed-by=/etc/apt/keyrings/example.gpg] https://apt.example.com stable main" | sudo tee /etc/apt/sources.list.d/example.list
sudo apt update && sudo apt install example-cli

# Or using the install script
curl -fsSL https://get.example.com/cli | sh

Windows

# Using Scoop
scoop bucket add example https://github.com/example/scoop-bucket
scoop install example-cli

# Or using winget
winget install Example.CLI

Verify Installation

example --version
# example-cli/1.5.0 darwin-arm64

Authentication

Before using most commands, authenticate with your API key:

# Interactive login (opens browser)
example auth login

# Or set API key directly
example auth login --api-key YOUR_API_KEY

# Verify authentication
example auth status

Environment Variables

Alternatively, set the API key via environment variable:

export EXAMPLE_API_KEY="your-api-key"

Global Options

These options work with all commands:

--help, -h          Show help for a command
--version, -v       Show CLI version
--config PATH       Use alternate config file (default: ~/.example/config.yaml)
--profile NAME      Use named profile from config file
--output, -o        Output format: table, json, yaml (default: table)
--quiet, -q         Suppress non-essential output
--verbose           Show detailed output including API calls
--no-color          Disable colored output

Command Reference

example projects

Manage projects in your account.

List projects

example projects list [flags]

Flags:
  --status STRING     Filter by status: active, archived, all (default: active)
  --limit INT         Maximum results to return (default: 20, max: 100)
  --sort STRING       Sort by: name, created, updated (default: created)

Examples:
  example projects list
  example projects list --status archived --limit 50
  example projects list -o json | jq '.[] | .name'

Create a project

example projects create NAME [flags]

Flags:
  --description, -d STRING    Project description
  --team STRING               Assign to team (team ID or name)
  --tags STRING               Comma-separated tags

Examples:
  example projects create "My Project"
  example projects create "API Server" -d "Backend services" --team backend
  example projects create "Web App" --tags "frontend,react,production"

Get project details

example projects get PROJECT_ID [flags]

Flags:
  --include-members    Include team member details

Examples:
  example projects get proj_abc123
  example projects get proj_abc123 --include-members -o yaml

Update a project

example projects update PROJECT_ID [flags]

Flags:
  --name STRING          New project name
  --description STRING   New description
  --status STRING        Set status: active, archived

Examples:
  example projects update proj_abc123 --name "Renamed Project"
  example projects update proj_abc123 --status archived

Delete a project

example projects delete PROJECT_ID [flags]

Flags:
  --force, -f    Skip confirmation prompt

Examples:
  example projects delete proj_abc123
  example projects delete proj_abc123 --force

example deployments

Manage deployments for a project.

List deployments

example deployments list --project PROJECT_ID [flags]

Flags:
  --project, -p STRING    Project ID (required)
  --status STRING         Filter: pending, running, succeeded, failed
  --limit INT             Maximum results (default: 20)

Examples:
  example deployments list -p proj_abc123
  example deployments list -p proj_abc123 --status failed

Create a deployment

example deployments create --project PROJECT_ID [flags]

Flags:
  --project, -p STRING     Project ID (required)
  --image STRING           Container image to deploy
  --env KEY=VALUE          Environment variable (can be repeated)
  --env-file PATH          Load env vars from file
  --replicas INT           Number of replicas (default: 1)
  --wait, -w               Wait for deployment to complete

Examples:
  example deployments create -p proj_abc123 --image myapp:v1.2.0
  example deployments create -p proj_abc123 --image myapp:latest \
    --env NODE_ENV=production \
    --env DATABASE_URL=postgres://... \
    --replicas 3 --wait

Get deployment status

example deployments get DEPLOYMENT_ID [flags]

Flags:
  --logs         Include recent logs
  --events       Include deployment events

Examples:
  example deployments get deploy_xyz789
  example deployments get deploy_xyz789 --logs --events

View deployment logs

example deployments logs DEPLOYMENT_ID [flags]

Flags:
  --follow, -f     Stream logs in real-time
  --tail INT       Number of lines from end (default: 100)
  --since STRING   Show logs since timestamp or duration (e.g., "1h", "2023-09-15")

Examples:
  example deployments logs deploy_xyz789
  example deployments logs deploy_xyz789 -f
  example deployments logs deploy_xyz789 --since 1h --tail 500

Rollback deployment

example deployments rollback DEPLOYMENT_ID [flags]

Flags:
  --to STRING      Rollback to specific deployment ID
  --wait, -w       Wait for rollback to complete

Examples:
  example deployments rollback deploy_xyz789
  example deployments rollback deploy_xyz789 --to deploy_abc456 --wait

example config

Manage CLI configuration.

View configuration

example config list

# Output:
# api_endpoint = https://api.example.com
# default_project = proj_abc123
# output_format = table

Set configuration value

example config set KEY VALUE

Examples:
  example config set default_project proj_abc123
  example config set output_format json

Get configuration value

example config get KEY

Examples:
  example config get api_endpoint
  # https://api.example.com

Manage profiles

# Create a new profile
example config profile create staging --api-key STAGING_KEY

# List profiles
example config profile list

# Switch default profile
example config profile use staging

# Delete a profile
example config profile delete staging

Output Formats

Table (default)

example projects list

ID            NAME           STATUS    CREATED
proj_abc123   My Project     active    2023-09-15
proj_def456   API Server     active    2023-08-22
proj_ghi789   Legacy App     archived  2023-04-10

JSON

example projects list -o json

[
  {
    "id": "proj_abc123",
    "name": "My Project",
    "status": "active",
    "created_at": "2023-09-15T10:30:00Z"
  },
  ...
]

YAML

example projects list -o yaml

- id: proj_abc123
  name: My Project
  status: active
  created_at: "2023-09-15T10:30:00Z"
...

Piping to jq

# Get just project names
example projects list -o json | jq -r '.[].name'

# Filter active projects
example projects list -o json | jq '.[] | select(.status == "active")'

# Count deployments by status
example deployments list -p proj_abc123 -o json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

Configuration File

The CLI reads configuration from ~/.example/config.yaml:

# ~/.example/config.yaml
api_endpoint: https://api.example.com
default_project: proj_abc123
output_format: table

profiles:
  default:
    api_key: sk_live_xxx
  staging:
    api_endpoint: https://api.staging.example.com
    api_key: sk_test_xxx
  production:
    api_key: sk_live_yyy
    default_project: proj_prod001

Profile Usage

# Use a specific profile
example --profile staging projects list

# Or set via environment variable
export EXAMPLE_PROFILE=staging
example projects list

Shell Completions

Enable tab completion for your shell:

Bash

example completion bash > /etc/bash_completion.d/example
# Or for user install:
example completion bash >> ~/.bashrc

Zsh

example completion zsh > "${fpath[1]}/_example"
# Then restart your shell or run: compinit

Fish

example completion fish > ~/.config/fish/completions/example.fish

Exit Codes

• 0 — Success
• 1 — General error (see stderr for details)
• 2 — Invalid command or arguments
• 3 — Authentication error (not logged in or invalid credentials)
• 4 — Resource not found
• 5 — Permission denied
• 6 — Network error (cannot reach API)
• 7 — Rate limited (retry after delay)

Using in Scripts

#!/bin/bash
set -e

if ! example auth status --quiet; then
  echo "Not authenticated. Please run: example auth login"
  exit 1
fi

example projects create "New Project" || {
  echo "Failed to create project"
  exit 1
}

echo "Project created successfully"

Troubleshooting

Connection issues

# Test connectivity
example auth status --verbose

# Check for proxy issues
export HTTPS_PROXY=http://proxy.example.com:8080
example auth status

Debug mode

# Show full API request/response
example --verbose projects list

# Even more detail
export EXAMPLE_DEBUG=1
example projects list

Reset configuration

# Remove all config and re-authenticate
rm -rf ~/.example
example auth login

Related Samples

• Quickstart Guide
• REST API Documentation
• Docker Deployment Guide

This is a sample article to demonstrate how I write.