@timbrix/cli

@timbrix/cli

  _____ _           _          _
 |_   _(_)_ __ ___ | |__  _ __(_)_  __
   | | | | '_ ` _ \| '_ \| '__| \ \/ /
   | | | | | | | | | |_) | |  | |>  <
   |_| |_|_| |_| |_|_.__/|_|  |_/_/\_\

Official CLI tool for the Timbrix API.

Installation

npm install -g @timbrix/cli
# or
pnpm add -g @timbrix/cli

Quick Start

# Login to your Timbrix account
timbrix login

# List your organizations
timbrix organizations list

# Create a webhook
timbrix webhooks create --org <organization-id>

# Logout
timbrix logout

Authentication

Login

timbrix login
# Or provide email directly
timbrix login --email [e-mail]

Credentials are saved to ~/.timbrix/config.json

Logout

timbrix logout

Commands

Organizations

# List all organizations
timbrix organizations list

# Get organization details
timbrix organizations get <slug>

# Create organization
timbrix organizations create
timbrix organizations create --name "Acme Corp" --slug acme-corp

# Delete organization (PERMANENT)
timbrix organizations delete <slug>
timbrix organizations delete <slug> --force  # Skip confirmation

Webhooks

# List webhooks
timbrix webhooks list --org <organization-id>

# Get webhook details
timbrix webhooks get <webhook-id> --org <organization-id>

# Create webhook
timbrix webhooks create --org <organization-id>
timbrix webhooks create --org <organization-id> --url https://example.com/webhook

# Delete webhook (PERMANENT)
timbrix webhooks delete <webhook-id> --org <organization-id>
timbrix webhooks delete <webhook-id> --org <organization-id> --force

Products

# List products/services for an organization
timbrix products list --org <organization-id>

# Get product details
timbrix products get <product-id> --org <organization-id>

# Create a product
timbrix products create --org <organization-id>
timbrix products create --org <organization-id> --description Ukelele --product-key 60131324 --price 345.60

# Update a product
timbrix products update <product-id> --org <organization-id>

# Bulk import products/services from a CSV file
timbrix products import --org <organization-id> --file ./products.csv

# Delete a product (PERMANENT)
timbrix products delete <product-id> --org <organization-id>

Invoices (CFDI 4.0)

# Stamp (timbrar) a new invoice — authenticates with an API key, not the login session
timbrix invoices create --org <organization-id> --api-key <api-key> --file invoice.json
timbrix invoices create --org <organization-id> --api-key <api-key> --file invoice.json --output invoice.xml

# List invoices for an organization (newest first)
timbrix invoices list --org <organization-id>
timbrix invoices list --org <organization-id> --page 2 --limit 50

# Get a single invoice by its folio fiscal (UUID)
timbrix invoices get <invoice-uuid>

# Download the timbrado XML or PDF for an invoice
timbrix invoices download <invoice-uuid> --format xml
timbrix invoices download <invoice-uuid> --format pdf --output invoice.pdf

# Email the XML and PDF of an invoice to its receptor
timbrix invoices email <invoice-uuid>
timbrix invoices email <invoice-uuid> --to [e-mail]

SAT Catalogs

# Search SAT claves de producto o servicio (c_ClaveProdServ)
timbrix sat claves-prod-serv --query ukelele
timbrix sat claves-prod-serv -q "servicios de consultoria" --limit 10

# Search SAT claves de unidad de medida (c_ClaveUnidad)
timbrix sat claves-unidad --query pieza
timbrix sat claves-unidad -q kilogramo --limit 10

# List SAT régimenes fiscales
timbrix sat regimenes list
timbrix sat regimenes list --tipo-persona moral

# List SAT usos de CFDI
timbrix sat usos-cfdi list
timbrix sat usos-cfdi list --regimen 601

API Keys

# List API keys
timbrix api-keys list --org <organization-id>

# Get API key details
timbrix api-keys get <api-key-id> --org <organization-id>

# Create API key
timbrix api-keys create --org <organization-id>
timbrix api-keys create --org <organization-id> --name "Production Key"
timbrix api-keys create --org <organization-id> --name "Staging Key" --expires 2025-12-31T23:59:59Z

# Revoke API key (PERMANENT)
timbrix api-keys delete <api-key-id> --org <organization-id>
timbrix api-keys delete <api-key-id> --org <organization-id> --force

Global Commands

# Show help for any command
timbrix --help
timbrix <command> --help

# Show CLI version
timbrix --version

# Update to latest version
timbrix update

Examples

Complete Workflow

# 1. Login
timbrix login

# 2. Create organization
timbrix organizations create --name "My Company" --slug my-company

# 3. Get organization ID
timbrix organizations get my-company
# Copy the ID from output

# 4. Create webhook
timbrix webhooks create --org <org-id> --url https://api.mycompany.com/webhooks

# 5. Create API key for external services
timbrix api-keys create --org <org-id> --name "Production API Key"

# 6. List all resources
timbrix organizations list
timbrix webhooks list --org <org-id>
timbrix api-keys list --org <org-id>

Using in CI/CD

# Set credentials as environment variable in CI
export TIMBRIX_TOKEN="your-token"

# Or login programmatically (if your API supports it)
echo "password" | timbrix login --email [e-mail]

# Create API key for deployment
timbrix api-keys create --org $ORG_ID --name "CI/CD Key"

Configuration

Configuration is stored in ~/.timbrix/config.json:

{
  "bearerToken": "eyJhbGc...",
  "email": "[e-mail]",
  "baseUrl": "http://localhost:3001"
}

To use a different API URL:

timbrix login --base-url https://api.timbrix.com

Theme Customization

The CLI comes with a modern color theme. Users can customize it by creating a theme.json file in ~/.timbrix/:

{
  "bin": "cyan",
  "command": "greenBright",
  "flag": "blueBright",
  "flagRequired": "redBright"
}

To disable the theme:

TIMBRIX_DISABLE_THEME=1 timbrix --help

Update Notifications

The CLI automatically checks for updates once per week and notifies you when a new version is available.

Update manually:

# Check and update to latest version
timbrix update

# The update command will:
# - Check for new versions
# - Detect your package manager (pnpm, yarn, or npm)
# - Update automatically to the latest version

Disable notifications:

NO_UPDATE_NOTIFIER=1 timbrix login

Features

🎨 Modern UI

• ASCII Logo: Beautiful Timbrix logo displayed on help and login commands
• Custom Theme: Vibrant color scheme with cyan, green, and blue highlights
• Syntax Highlighting: Color-coded JSON output for better readability

🔔 Update Notifications

The CLI automatically checks for new versions once per week and notifies you when an update is available. Checks are non-blocking and respect CI environments.

🛠️ Built with

• oclif: Modern CLI framework
• TypeScript: Type-safe development
• chalk: Terminal colors
• inquirer: Interactive prompts
• ora: Elegant spinners
• cli-table3: Beautiful tables

Architecture

src/
├── commands/           # CLI commands
│   ├── login.ts       # Authentication
│   ├── logout.ts
│   ├── organizations/ # Organization management
│   ├── webhooks/      # Webhook management
│   ├── api-keys/      # API key management
│   ├── products/      # Products/services + CSV import
│   └── sat/           # SAT catalog search (claves, régimenes, usos CFDI)
├── config/
│   └── auth.ts        # Auth configuration manager
├── utils/
│   ├── logo.ts        # ASCII logo
│   ├── table.ts       # Table formatting
│   ├── client.ts      # API client
│   └── update-notifier.ts
├── hooks/
│   └── init/
│       └── update-check.ts  # Update check hook
└── help.ts            # Custom help class

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run locally with hot-reload
pnpm dev

# Link for local testing
pnpm link --global

# Type check
pnpm check-types

# Lint
pnpm lint

Troubleshooting

Authentication Error

Error: Not authenticated. Please run 'timbrix login' first.

Solution: Run timbrix login to authenticate.

API Connection Error

Failed to fetch organizations: connect ECONNREFUSED

Solution: Check that your API is running and the base URL is correct.

Invalid Token

Authentication failed: 401 Unauthorized

Solution: Your token may have expired. Run timbrix logout then timbrix login again.

License

MIT