☕ Barista CLI

让 AI 助手操控生产管理系统 — Bridge AI tools (Claude Code, OpenCode, OpenClaw) to enterprise SaaS

⚡ Quick Start

1. Install

npm install -g @newpeak/barista-cli

2. Authenticate

# AI needs credentials to operate on behalf of user
barista liberica auth login prod-cn your-tenant your-username your-password

# Interactive login (prompts for missing info)
barista liberica auth login

3. AI Integration

// In Claude Code / OpenCode / OpenClaw:
const orders = await $`barista liberica orders list --env prod-cn --tenant your-tenant --json`
const { success, data } = JSON.parse(orders.stdout)

// AI parses and acts on the data
if (data.items.length > 0) {
  console.log(`Found ${data.pagination.total} orders`)
}

View AI Integration Examples →

🤖 AI Integration

Barista CLI is designed for AI coding assistants. Every output is structured, every error is actionable.

Supported AI Tools

| AI Tool | Integration Method | Status | |---------|-------------------|--------| | Claude Code | $ backticks + --json | ✅ Verified | | OpenCode | Shell command + JSON parse | ✅ Verified | | OpenClaw | Shell command + JSON parse | ✅ Verified | | Cursor | Terminal integration | ✅ Compatible | | Continue | CLI subprocess | ✅ Compatible |

Integration Pattern

// 1. Execute command with JSON output
const result = await $`barista liberica orders list \
  --env prod-cn \
  --tenant your-tenant \
  --status pending \
  --json \
  --page 1 \
  --size 50`

// 2. Parse structured response
const { success, data, meta } = JSON.parse(result.stdout)

if (!success) {
  throw new Error(`API Error: ${meta.code || meta.error?.code} - ${meta.message || meta.error?.message}`)
}

// 3. Work with data
const pendingOrders = data.items
console.log(`Found ${data.pagination.total} pending orders`)

// 4. Execute operations safely
for (const order of pendingOrders) {
  // Always dry-run first (AI safety)
  const preview = await $`barista liberica orders cancel ${order.id} --dry-run`

  // Parse preview, verify, then execute with --force
  // ...
}

Response Envelope

All JSON responses follow this structure:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": { "page": 1, "size": 20, "total": 150 }
  },
  "meta": {
    "requestId": "req-abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "environment": "prod-cn",
    "tenant": "your-tenant"
  }
}

Error format:

{
  "success": false,
  "error": {
    "code": "A150001",
    "message": "Order not found"
  },
  "meta": {
    "requestId": "req-xyz789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Skills for Claude Code

Install reusable skill files:

# Skills are located at ~/.barista/claude/skills/
barista skills install

Available skills:

• orders.md — Order management workflow
• products.md — Product search and sync
• warehouses.md — Inventory operations
• subscriptions.md — Arabica subscription management

🚀 Features

AI-First Design

| Feature | Description | |---------|-------------| | 🤖 JSON-First Output | All commands support --json for AI parsing | | 📦 Structured Responses | Consistent {success, data, meta} envelope | | 🔄 Idempotent Operations | Safe for AI retry loops | | 🛡️ Dry-Run by Default | Destructive operations preview before execution | | 🔐 Secure Storage | Credentials in system keychain, not env vars |

Enterprise Connectivity

| Service | Capabilities | |---------|-------------| | ☕ Liberica | Orders, products, inventory, warehouses, production planning | | 🛒 Arabica | Subscription plans, billing, invoices, enterprise management | | 🔗 Cross-Service | Quote from order, sync between systems |

Operational Safety

• 📊 Audit Trail — Every operation logged with request ID
• ⚠️ Confirmation Guards — --dry-run / --force for write operations
• 🏢 Multi-Tenant Isolation — Credentials isolated per tenant

🔧 Command Reference

Core Pattern

barista <service> <resource> <action> [options]

Global Options

| Option | Description | Default | |--------|-------------|---------| | --env | Environment (dev|test|prod-cn|prod-jp) | dev | | --tenant | Tenant name | - | | --json | JSON output | false | | --dry-run | Preview mode (recommended for AI) | false | | --force | Skip confirmation | false | | --page | Page number | 1 | | --size | Page size (max items) | 20 |

Quick Reference

| Command | Description | |---------|-------------| | barista context show | Show current env/tenant context | | barista context use-env <env> | Switch environment | | barista liberica orders list --json | List orders (AI format) | | barista liberica orders get <id> --json | Get order detail | | barista liberica orders create --dry-run ... | Preview create | | barista liberica products search --keyword <kw> --json | Search products | | barista arabica plans list --json | List subscription plans | | barista arabica invoices list --json | List invoices |

→ Full Command Reference

🛡️ AI Safety Guidelines

1. Always Dry-Run First

// ❌ Wrong - executing blindly
await $`barista liberica orders cancel 12345`

// ✅ Correct - preview first
const preview = await $`barista liberica orders cancel 12345 --dry-run`
// Parse preview, verify correctness, then:
await $`barista liberica orders cancel 12345 --force`

2. Check Success Before Proceeding

const result = JSON.parse(stdout)
if (!result.success) {
  // Handle error, don't continue
  throw new Error(result.error?.message || result.meta?.message)
}

3. Use Request IDs for Debugging

const { meta } = JSON.parse(stdout)
console.log(`Request ID: ${meta.requestId}`)

4. Respect Rate Limits

• Add delays between bulk operations
• Use --size 100 for bulk fetches
• Cache responses when appropriate

⚙️ Configuration

File Location

~/.barista/config.yaml

Quick Config

defaults:
  env: prod-cn
  tenant: your-tenant
  service: liberica

environments:
  prod-cn:
    liberica:
      baseUrl: "https://{tenant}.newpeaksh.com"
      timeout: 60000
    arabica:
      baseUrl: "https://www.newpeaksh.com"
      timeout: 60000

Authentication

# Credential login (recommended)
barista liberica auth login <env> <tenant> <username> <password>

# Check auth status
barista auth status

# Logout
barista auth logout --service liberica --env prod-cn

❓ Troubleshooting

Auth Failures

# Check current status
barista auth status

# Re-authenticate
barista liberica auth login prod-cn your-tenant your-username your-password

# Check context
barista context show

API Errors

# Always use --json to get error codes
barista liberica orders list --json

# Error response includes requestId for debugging
# "requestId": "req-abc123"

Timeout Issues

# Switch to closer environment
barista context use-env dev

# Or adjust timeout in config.yaml

📚 Related Projects

| Project | Description | |---------|-------------| | ☕ Liberica Backend | Production management SaaS backend | | 🖥️ Liberica Frontend | Production management web UI | | 📱 Liberica Mobile | Production management mobile app | | 🛒 Arabica Backend | Online subscription SaaS backend | | 🌐 Arabica Frontend | Online subscription web UI |

📄 License

MIT © Newpeak Technology