CLI Reference

Complete reference for all Braids CLI commands, flags, and usage patterns.

Global Flags#

These flags work with any command:

braids init#

Usage: braids init [flags]

Initialize a new braids project. Creates a braids.yaml in the current directory with a starter configuration (Stripe + Shopify example). Fails if the file already exists.

Flags

Examples

$ braids init
Created braids.yaml
Next steps:
  1. Set environment variables: STRIPE_API_KEY, SHOPIFY_STORE, SHOPIFY_ACCESS_TOKEN
  2. Run: braids validate
  3. Run: braids serve

$ braids init --demo
Created braids.yaml
Next steps:
  1. Run: braids validate
  2. Run: braids serve
  3. Try: curl http://localhost:8080/users

braids validate#

Usage: braids validate

Validate braids.yaml configuration. Checks:

• version field is present and supported
• Connector definitions have a valid type and required config
• Schema definitions with valid field types (string, number, boolean, datetime, object, array)
• Endpoint sources reference defined connectors and schemas with mappings
• Server port range is valid (0–65535)

Examples

Success output:

$ braids validate
braids.yaml is valid

Error output:

$ braids validate
Error: connector "stripe" is missing required field: type

braids serve#

Usage: braids serve [flags]

Start the Braids gateway. Loads config, initializes connectors, validates schemas, and starts the HTTP server. Supports graceful shutdown on SIGINT/SIGTERM. If hot_reload is enabled, watches config for changes.

Flags

Examples

$ braids serve

■ Braids Gateway v0.2.0
────────────────────────────────────

✓ Config loaded            braids.yaml
✓ Connector ready          shopify
✓ Connector ready          stripe
✓ Schema validated         1 endpoint, 2 sources
✓ Merge strategy           prefer_latest on "email"

■ Gateway listening on     http://localhost:8080

  Endpoints:
  GET  /customers               stripe + shopify

  Press Ctrl+C to stop

With debug mode:

$ braids serve --debug
[DEBUG] Incoming: GET /customers → matched endpoint
[DEBUG] Source stripe/customers: 25 records, 142ms elapsed
[DEBUG] Source shopify/customers: 18 records, 238ms elapsed

braids connectors list#

Usage: braids connectors list

List all 32 built-in connectors, grouped by category with descriptions.

Example

$ braids connectors list

AI:
  openai           AI and large language model API platform

AUTHENTICATION:
  clerk            Authentication and user management platform

CLOUD-INFRASTRUCTURE:
  cloudflare       Web performance and security platform
  digitalocean     Cloud infrastructure provider for developers
  vercel           Frontend deployment and serverless platform

COMMUNICATION:
  discord          Voice, video, and text communication platform
  slack            Business communication and messaging platform
  twilio           Cloud communications platform for SMS, voice, and messaging
  zoom             Video conferencing and online meetings platform

CRM:
  hubspot          CRM, marketing, and sales platform

  ...

32 connectors available

braids connectors update#

Usage: braids connectors update

Download or refresh cached OpenAPI specs for all connectors that have an openapi_url defined.

Example

$ braids connectors update
  stripe: downloading https://raw.githubusercontent.com/.../spec3.json ...
  stripe: cached
  github: downloading https://raw.githubusercontent.com/.../api.github.com.json ...
  github: cached

braids extensions list#

Usage: braids extensions list

List available extension protocols and their installation status.

Example

$ braids extensions list
EXTENSIONS:
  grpc                     not installed
  mongodb                  not installed
  mysql       v0.1.0       installed 2025-03-10
  postgres    v0.1.0       installed 2025-03-10

4 extensions available, 2 installed

Install with: braids extensions install <protocol>

braids extensions install#

Usage: braids extensions install <protocol>

Download and install an extension binary. Supported protocols: postgres, mysql, mongodb, grpc. Downloads from GitHub releases with SHA256 verification.

Example

$ braids extensions install postgres
Downloading braids-ext-postgres v0.2.0...
Verifying checksum... ok
Installed to ~/.braids/extensions/braids-ext-postgres

braids extensions update#

Usage: braids extensions update [protocol]

Update installed extensions to their latest versions. If no protocol is specified, updates all installed extensions.

Example

$ braids extensions update
Updating postgres... v0.2.0 → v0.2.1
Updating mysql... already up to date
2 extensions checked

braids version#

Usage: braids version

Print version information.

Example

$ braids version
braids v0.2.0 (abc1234)