npm package: @meshbase/cli
Description: Meshbase CLI — interact with your data from the terminal
Latest version: 0.1.3

# @meshbase/cli

Meshbase CLI for terminals, scripts, CI, and AI agents.

Published npm package: `@meshbase/cli`
Executable after install: `meshbase`

## Installation

```bash
npm install -g @meshbase/cli
# or
pnpm add -g @meshbase/cli
```

Run without installing:

```bash
npx @meshbase/cli@latest --help
```

## Authentication

### Environment variables (recommended for CI/CD and AI agents)

```bash
export MESHBASE_API_KEY=mb_wk_...
export MESHBASE_API_URL=https://api.meshbase.ai
export MESHBASE_ORG_SLUG=acme-corp
```

When `MESHBASE_API_KEY` is set, it takes priority over profile-based auth.

### Interactive setup

```bash
meshbase init                    # guided wizard
meshbase login                   # browser-based sign-in
meshbase login --api-key mb_wk_... --api-url https://api.meshbase.ai --org acme-corp
```

### Headless / CI export

```bash
meshbase auth export > creds.json       # export active profile (decrypted)
meshbase auth import creds.json         # import on another machine
```

### Auth precedence

| Priority | Source | Set via |
|----------|--------|---------|
| 1 | Environment variable | `MESHBASE_API_KEY` |
| 2 | Active profile | `meshbase login` / `~/.meshbase/config.json` |

Credentials in profiles are encrypted at rest (AES-256-GCM) in `~/.meshbase/config.json`.

## Environment Variables

All optional. Environment variables override profile settings.

| Variable | Description |
|----------|-------------|
| `MESHBASE_API_KEY` | API key (highest priority auth) |
| `MESHBASE_API_URL` | Public API URL. This should point to Apollo Router (default local: `http://localhost:4000`) and is also used to derive management API requests |
| `MESHBASE_MANAGEMENT_API_URL` | Optional management API override for split deployments or local debugging |
| `MESHBASE_ORG_SLUG` | Organization slug |
| `MESHBASE_CONFIG_DIR` | Override config directory (default: `~/.meshbase`) |

When extracted subgraphs are enabled, keep `MESHBASE_API_URL` on the
Router entry point. Do not point the CLI at an individual subgraph unless you
are debugging that subgraph directly.

For hosted Meshbase, `MESHBASE_API_URL=https://api.meshbase.ai` is enough for
both data and management commands.

## Status

Check connectivity and session info:

```bash
meshbase status              # human-readable dashboard
meshbase status -f json      # structured JSON for scripts
```

## Domain Commands

Every business-data graph domain has typed commands with `list`, `get`, `create`, `update`, and `archive`/`cancel` where applicable. All mutations support `--dry-run`.

### Core Domains

```bash
# Catalog — products, categories, brands
meshbase catalog products list --first 10 --search "outdoor" -f table
meshbase catalog products create --input '{"name":"Widget","sku":"W-001"}' --dry-run
meshbase catalog products update prod_123 --input '{"name":"Super Widget"}'
meshbase catalog products archive prod_123
meshbase catalog categories list
meshbase catalog brands list

# Commerce — orders, cart
meshbase commerce orders list --first 20 -f table
meshbase commerce orders create --input '{"customerId":"cust_1","items":[...]}'
meshbase commerce orders status ord_123 SHIPPED
meshbase commerce cart add prod_123 --quantity 2
meshbase commerce cart checkout cart_123 cust_123 --ref "PO-2024-001"

# Identity — customers
meshbase identity customers list --search "acme" -f table
meshbase identity customers create --input '{"companyName":"Acme","email":"a@b.com"}'
meshbase identity customers update cust_123 --input '{"email":"new@b.com"}'

# Invoice — invoices (with pay/void)
meshbase invoice invoices list -f table
meshbase invoice invoices create --input '{"customerId":"cust_1","lines":[...]}'
meshbase invoice invoices pay inv_123
meshbase invoice invoices void inv_123

# Payment — payments, credit notes
meshbase payment payments list -f table
meshbase payment payments create --input '{"invoiceId":"inv_1","amount":100}'

# Quote
meshbase quote quotes list -f table
meshbase quote quotes create --input '{"customerId":"cust_1","lines":[...]}'

# Contract
meshbase contract contracts list -f table
meshbase contract contracts create --input '{"name":"SLA","customerId":"cust_1"}'

# Document
meshbase document documents list -f table
meshbase document documents create --input '{"name":"Report Q4","type":"PDF"}'
```

### Operations & Logistics

```bash
# Inventory — warehouses, stock
meshbase inventory warehouses list -f table
meshbase inventory stock levels --product prod_123 -f table
meshbase inventory stock adjust --input '{"warehouseId":"wh_1","productId":"prod_1","delta":10}'
meshbase inventory stock set --input '{"warehouseId":"wh_1","productId":"prod_1","quantity":100}'

# Procurement — purchase orders, goods receipts
meshbase procurement purchase-orders list -f table
meshbase procurement purchase-orders create --input '{"supplierId":"sup_1","lines":[...]}'
meshbase procurement goods-receipts create --input '{"purchaseOrderId":"po_1"}'

# Logistics — shipments, drivers
meshbase logistics shipments list -f table
meshbase logistics shipments create --input '{"orderId":"ord_1","carrier":"DHL"}'

# Stock Movement
meshbase stock-movement movements list -f table

# Asset tracking
meshbase asset assets list -f table
meshbase asset assets create --input '{"name":"Forklift","serialNumber":"FK-001"}'
```

### Services & Projects

```bash
# Service catalog
meshbase service services list -f table
meshbase service services create --input '{"name":"Consulting","rate":150}'

# Project management
meshbase project projects list -f table
meshbase project projects create --input '{"name":"Website Redesign","status":"PLANNING"}'

# Time tracking
meshbase time-tracking entries list -f table
meshbase time-tracking entries create --input '{"projectId":"proj_1","hours":8}'

# Approval workflows
meshbase approval requests list -f table
meshbase approval requests create --input '{"type":"PURCHASE","referenceId":"po_1"}'
```

### Booking & Events

```bash
# Booking — appointments, resources
meshbase booking appointments list --first 10 -f table
meshbase booking appointments create --input '{"resourceId":"res_1","startsAt":"2024-01-15T10:00:00Z"}'
meshbase booking appointments cancel apt_123

# Events & registrations
meshbase event events list -f table
meshbase event events create --input '{"name":"Conference","date":"2024-06-01"}'
meshbase event registrations create --input '{"eventId":"evt_1","attendeeEmail":"a@b.com"}'
```

### Industry Domains

```bash
# Healthcare — patients, encounters
meshbase healthcare patients list -f table
meshbase healthcare patients create --input '{"firstName":"Jane","lastName":"Doe"}'

# Education — courses, students
meshbase education courses list -f table
meshbase education students create --input '{"firstName":"John","email":"j@school.com"}'

# Agriculture — fields, crops, livestock, certifications
meshbase agriculture fields list -f table
meshbase agriculture crops list
meshbase agriculture livestock create --input '{"tag":"L-001","species":"cattle"}'

# Hospitality — guests, menus, housekeeping, channels
meshbase hospitality guests list -f table
meshbase hospitality menus list
meshbase hospitality housekeeping create --input '{"room":"301","type":"DEEP_CLEAN"}'

# Real Estate — properties, leases
meshbase real-estate properties list -f table
meshbase real-estate leases create --input '{"propertyId":"prop_1","tenantId":"cust_1"}'

# EV Charging — stations, sessions
meshbase charging stations list -f table
meshbase charging sessions list

# Manufacturing (MRP) — work orders, BOMs
meshbase mrp work-orders list -f table
meshbase mrp boms create --input '{"productId":"prod_1","components":[...]}'
```

### More Domains

```bash
meshbase subscription plans list              # subscription plans
meshbase tax rules list                       # tax rules
meshbase guide guides list                    # knowledge base guides
```

Run `meshbase <domain> --help` for the full command tree of any domain.

### Webhook

```bash
meshbase webhook webhooks list -f table
meshbase webhook webhooks create --name "ERP Sync" --url https://erp.example.com/hook --events commerce.order_created
meshbase webhook webhooks test wh_123 --event commerce.order_created
meshbase webhook webhooks deliveries wh_123
meshbase webhook listen --port 4444
```

## Generic Commands

For ad-hoc operations beyond domain commands:

```bash
meshbase query products --first 10 --search "outdoor" --fields "id,name,priceNet" -f table
meshbase get product prod_123 --fields "id,name,sku,priceNet"
meshbase create createProduct --input '{"name":"Test"}' --dry-run
meshbase update updateProduct prod_123 --input '{"name":"Updated"}'
meshbase delete archiveProduct prod_123
meshbase graphql 'query { products(first: 5) { edges { node { id name } } } }'
meshbase graphql --file my-query.graphql --variables '{"id":"prod_1"}' --dry-run
meshbase ask "How many orders this month?"
```

## Schema Introspection

```bash
meshbase schema queries                        # list all queries
meshbase schema mutations                      # list all mutations
meshbase schema describe Product               # show fields for a type
meshbase schema describe CreateProductInput --example   # generate sample JSON
```

## Interactive Mode

```bash
meshbase interactive    # or: meshbase i
```

Type questions for NLQ, prefix `gql:` for raw GraphQL, `format table` to switch output.

## Bulk Data

```bash
meshbase data export products --fields "id,name,sku" -f csv > products.csv
meshbase data export orders -f jsonl > orders.jsonl
meshbase data import products --file products.csv
meshbase data import products --file data.jsonl --dry-run --continue-on-error
```

## Provider Context Switching

```bash
meshbase connect acme-data              # subscribe + switch in one step
meshbase use acme-data                  # switch to existing subscription
meshbase use default                    # return to own workspace
```

## Code Generation

```bash
meshbase codegen                        # outputs meshbase.d.ts
meshbase codegen --output src/types/api.ts
```

## AI Agent Skills

Generate SKILL.md reference files for all domains:

```bash
meshbase generate-skills --output ./skills
```

Produces one skill file per domain plus a shared reference — derived from the live API schema.

## Profiles

```bash
meshbase profiles list
meshbase profiles create staging --api-url https://api-staging.meshbase.ai --api-key mb_wk_...
meshbase profiles use staging
meshbase profiles delete staging
meshbase auth export > profile.json     # export for CI
meshbase auth import profile.json       # import on another machine
```

## Global Options

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Enable debug output (request/response logging) |
| `-q, --quiet` | Suppress all stderr output (spinners, hints, banners) |
| `-f, --format` | Output format: `json`, `table`, `csv`, `jsonl` |
| `--fields` | Limit output to specific fields (comma-separated, applied globally) |
| `-y, --yes` | Skip confirmation prompts |
| `--dry-run` | Preview mutations without executing |
| `--first` | Number of results to return |
| `--after` | Pagination cursor for next page |
| `--search` | Full-text search filter |

## Output Format

All data goes to stdout as structured output. Metadata (pagination, hints) goes to stderr.

Errors are JSON on stdout:

```json
{ "error": { "code": "NOT_FOUND", "message": "...", "hint": "Verify the ID or entity name..." } }
```

Use `--quiet` for pure machine consumption (no stderr output at all).

## Shell Completion

```bash
meshbase completion bash >> ~/.bashrc
meshbase completion zsh >> ~/.zshrc
meshbase completion fish >> ~/.config/fish/completions/meshbase.fish
```

Completions include all subcommands and descriptions.