☕ 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

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

Enterprise Connectivity

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

Quick Reference

→ 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

📄 License

MIT © Newpeak Technology