CLI Reference

Barbacane provides two command-line tools:

• barbacane - Data plane (gateway) for compiling specs and serving traffic
• barbacane-control - Control plane for managing specs, plugins, and artifacts via REST API

barbacane

barbacane <COMMAND> [OPTIONS]

Commands

barbacane init

Initialize a new Barbacane project with manifest, spec, and directory structure.

barbacane init [NAME] [OPTIONS]

Arguments

Options

Plugin Download

The --fetch-plugins flag downloads official Barbacane plugins from GitHub releases:

• mock — Returns static responses (useful for testing and mocking)
• http-upstream — Proxies requests to HTTP/HTTPS backends

Downloaded plugins are placed in the plugins/ directory and automatically configured in barbacane.yaml.

# Create project with plugins downloaded
barbacane init my-api --fetch-plugins

If download fails (e.g., network issues), the project is still created with an empty plugins directory.

Templates

basic (default):

• Complete OpenAPI spec with /health and /users endpoints
• Example x-barbacane-dispatch configurations
• Ready to compile and run

minimal:

• Bare-bones OpenAPI spec with just the required structure
• Single /health endpoint placeholder
• Start from scratch

Examples

# Create project in new directory with basic template
barbacane init my-api

# Create project with official plugins downloaded
barbacane init my-api --fetch-plugins

# Create project with minimal template
barbacane init my-api --template minimal

# Initialize in current directory
barbacane init .

# Short form
barbacane init my-api -t minimal

Generated Files

my-api/
├── barbacane.yaml    # Project manifest (plugin declarations)
├── api.yaml          # OpenAPI 3.1 specification
├── plugins/          # Directory for WASM plugins
└── .gitignore        # Ignores *.bca, target/, plugins/*.wasm

Exit Codes

barbacane compile

Compile one or more OpenAPI specs into a .bca artifact.

barbacane compile --spec <FILES>... --output <PATH>

Options

Examples

# Compile single spec with manifest
barbacane compile --spec api.yaml --manifest barbacane.yaml --output api.bca

# Compile multiple specs
barbacane compile -s users.yaml -s orders.yaml -m barbacane.yaml -o combined.bca

# Short form
barbacane compile -s api.yaml -m barbacane.yaml -o api.bca

# Legacy compilation without manifest (no plugins bundled)
barbacane compile -s api.yaml -o api.bca

Exit Codes

barbacane validate

Validate specs without full compilation. Checks for spec validity and extension errors.

barbacane validate --spec <FILES>... [OPTIONS]

Options

Error Codes

Examples

# Validate single spec
barbacane validate --spec api.yaml

# Validate multiple specs (checks for routing conflicts)
barbacane validate -s users.yaml -s orders.yaml

# JSON output (for CI/tooling)
barbacane validate --spec api.yaml --format json

Output Examples

Text format (default):

✓ api.yaml is valid

validated 1 spec(s): 1 valid, 0 invalid

Text format with errors:

✗ api.yaml has 1 error(s)
  E1004 [api.yaml]: E1004: schema validation error: missing 'info' object

validated 1 spec(s): 0 valid, 1 invalid

JSON format:

{
  "results": [
    {
      "file": "api.yaml",
      "valid": true,
      "errors": [],
      "warnings": []
    }
  ],
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

Exit Codes

barbacane serve

Run the gateway server, loading routes from a compiled artifact.

barbacane serve --artifact <PATH> [OPTIONS]

Options

Examples

# Run with defaults (HTTP)
barbacane serve --artifact api.bca

# Custom port
barbacane serve --artifact api.bca --listen 127.0.0.1:3000

# Development mode (verbose errors)
barbacane serve --artifact api.bca --dev

# Production with TLS (HTTPS)
barbacane serve --artifact api.bca \
  --tls-cert /etc/barbacane/certs/server.crt \
  --tls-key /etc/barbacane/certs/server.key

# Production with custom limits
barbacane serve --artifact api.bca \
  --max-body-size 5242880 \
  --max-headers 50

# With observability (OTLP export)
barbacane serve --artifact api.bca \
  --log-format json \
  --otlp-endpoint http://otel-collector:4317

# Development mode with pretty logging
barbacane serve --artifact api.bca --dev --log-format pretty

# All options
barbacane serve --artifact api.bca \
  --listen 0.0.0.0:8080 \
  --tls-cert /etc/barbacane/certs/server.crt \
  --tls-key /etc/barbacane/certs/server.key \
  --log-level info \
  --log-format json \
  --otlp-endpoint http://otel-collector:4317 \
  --max-body-size 1048576 \
  --max-headers 100 \
  --max-header-size 8192 \
  --max-uri-length 8192

TLS Termination

The gateway supports HTTPS with TLS termination. To enable TLS, provide both --tls-cert and --tls-key:

barbacane serve --artifact api.bca \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key

For maximum security with TLS 1.3 only (modern clients):

barbacane serve --artifact api.bca \
  --tls-cert /path/to/server.crt \
  --tls-key /path/to/server.key \
  --tls-min-version 1.3

TLS Configuration:

• Minimum TLS version: 1.2 (default) or 1.3 (via --tls-min-version)
• Modern cipher suites (via aws-lc-rs)
• ALPN support for HTTP/2 and HTTP/1.1

Certificate Requirements:

• Certificate and key must be in PEM format
• Certificate file can contain the full chain (cert + intermediates)
• Both --tls-cert and --tls-key must be provided together

HTTP/2 Support

The gateway supports both HTTP/1.1 and HTTP/2 with automatic protocol detection:

• With TLS: HTTP/2 is negotiated via ALPN (Application-Layer Protocol Negotiation). Clients that support HTTP/2 will automatically use it when connecting over HTTPS.
• Without TLS: HTTP/1.1 is used by default. HTTP/2 cleartext (h2c) is also supported via protocol detection.

HTTP/2 Features:

• Multiplexed streams over a single connection
• Header compression (HPACK)
• Keep-alive with configurable ping intervals (20 seconds)
• Full support for all gateway features (routing, validation, middlewares)

No configuration is needed—HTTP/2 works automatically when TLS is enabled. To verify HTTP/2 is working:

# Test HTTP/2 with curl
curl -v --http2 https://localhost:8080/__barbacane/health

# Expected output shows HTTP/2:
# * Using HTTP/2
# < HTTP/2 200

Development Mode

The --dev flag enables:

• Verbose error messages with field names, locations, and detailed reasons
• Extended RFC 9457 problem details with errors array
• Useful for debugging but do not use in production - it may expose internal information

Request Limits

The gateway enforces request limits to protect against abuse:

Requests exceeding limits receive an RFC 9457 problem details response:

{
  "type": "urn:barbacane:error:validation-failed",
  "title": "Request validation failed",
  "status": 400,
  "detail": "request body too large: 2000000 bytes exceeds limit of 1048576 bytes"
}

Graceful Shutdown

The gateway handles shutdown signals (SIGTERM, SIGINT) gracefully:

1. Stop accepting new connections immediately
2. Drain in-flight requests for up to --shutdown-timeout seconds (default: 30)
3. Force close any remaining connections after timeout
4. Exit with code 0 on successful shutdown

# Send SIGTERM to gracefully shutdown
kill -TERM $(pgrep barbacane)

# Output during graceful shutdown
barbacane: received shutdown signal, draining connections...
barbacane: waiting for 3 active connection(s) to complete...
barbacane: all connections drained, shutting down

Response Headers

Every response includes these standard headers:

Example response headers:

HTTP/1.1 200 OK
Server: barbacane/0.1.0
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Trace-Id: 4bf92f3577b34da6a3ce929d0e0e4736
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Type: application/json

API Lifecycle Headers

For deprecated operations, additional headers are included:

Example for deprecated endpoint:

HTTP/1.1 200 OK
Server: barbacane/0.1.0
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Content-Type: application/json

See API Lifecycle for configuration details.

Exit Codes

Exit code 13 occurs when a secret reference in your spec cannot be resolved:

$ export OAUTH2_SECRET=""  # unset the variable
$ unset OAUTH2_SECRET
$ barbacane serve --artifact api.bca
error: failed to resolve secrets: environment variable not found: OAUTH2_SECRET
$ echo $?
13

Environment Variables

Observability

Barbacane provides built-in observability features:

Logging

Structured logs are written to stdout in either JSON (default) or pretty format:

# JSON format (production)
barbacane serve --artifact api.bca --log-format json

# Pretty format (development)
barbacane serve --artifact api.bca --log-format pretty --log-level debug

Metrics

Prometheus metrics are exposed at /__barbacane/metrics:

curl http://localhost:8080/__barbacane/metrics

Key metrics include:

• barbacane_requests_total - Request counter by method, path, status
• barbacane_request_duration_seconds - Request latency histogram
• barbacane_active_connections - Current connection count
• barbacane_validation_failures_total - Validation error counter

Distributed Tracing

Enable OTLP export to send traces to OpenTelemetry Collector:

barbacane serve --artifact api.bca \
  --otlp-endpoint http://otel-collector:4317

Barbacane supports W3C Trace Context propagation (traceparent/tracestate headers) for distributed tracing across services.

Secret References

Dispatcher and middleware configs can reference secrets using special URI schemes. These are resolved at startup:

Example config with secrets:

x-barbacane-middlewares:
  - name: oauth2-auth
    config:
      client_secret: "env://OAUTH2_SECRET"

Run with:

export OAUTH2_SECRET="my-secret-value"
barbacane serve --artifact api.bca

See Secrets Guide for full documentation.

Common Workflows

Development Cycle

# Edit spec and manifest
vim api.yaml barbacane.yaml

# Validate (quick check)
barbacane validate --spec api.yaml

# Compile with manifest
barbacane compile --spec api.yaml --manifest barbacane.yaml --output api.bca

# Run in dev mode
barbacane serve --artifact api.bca --dev

CI/CD Pipeline

#!/bin/bash
set -e

# Validate all specs
barbacane validate --spec specs/*.yaml --format json > validation.json

# Compile artifact with manifest
barbacane compile \
  --spec specs/users.yaml \
  --spec specs/orders.yaml \
  --manifest barbacane.yaml \
  --output dist/gateway.bca

echo "Artifact built: dist/gateway.bca"

Multi-Spec Gateway

# Compile multiple specs into one artifact
barbacane compile \
  --spec users-api.yaml \
  --spec orders-api.yaml \
  --spec payments-api.yaml \
  --output combined.bca

# Routes from all specs are merged
# Conflicts (same path+method) cause E1010 error

Testing Locally

# Start gateway
barbacane serve --artifact api.bca --dev --listen 127.0.0.1:8080 &

# Test endpoints
curl http://localhost:8080/health
curl http://localhost:8080/__barbacane/health
curl http://localhost:8080/__barbacane/openapi

# Stop gateway
kill %1

barbacane-control

The control plane CLI for managing specs, plugins, and artifacts via REST API.

barbacane-control <COMMAND> [OPTIONS]

Commands

barbacane-control seed-plugins

Seed the plugin registry with built-in plugins from the local plugins/ directory. This command scans plugin directories, reads their manifests (plugin.toml), and registers them in the database.

barbacane-control seed-plugins [OPTIONS]

Options

The --database-url can also be set via the DATABASE_URL environment variable.

Plugin Directory Structure

Each plugin directory should contain:

plugins/
├── http-upstream/
│   ├── plugin.toml          # Plugin manifest (required)
│   ├── config-schema.json   # JSON Schema for config (optional)
│   ├── http-upstream.wasm   # Compiled WASM binary (required)
│   └── src/
│       └── lib.rs
├── rate-limit/
│   ├── plugin.toml
│   ├── config-schema.json
│   └── rate-limit.wasm
└── ...

Plugin Manifest (plugin.toml)

[plugin]
name = "http-upstream"
version = "0.1.0"
type = "dispatcher"                    # or "middleware"
description = "HTTP upstream proxy"    # optional
wasm = "http-upstream.wasm"           # optional, defaults to {name}.wasm

[capabilities]
host_functions = ["host_http_call", "host_log"]

Examples

# Build plugins and seed them into the registry
make seed-plugins

# Or manually:
cargo run -p barbacane-control -- seed-plugins \
  --plugins-dir plugins \
  --database-url postgres://localhost/barbacane \
  --verbose

# Output:
#   Registered http-upstream v0.1.0 (dispatcher)
#   Registered rate-limit v0.1.0 (middleware)
#   Registered cors v0.1.0 (middleware)
#   ...
# Seeded 9 plugin(s) into the registry.

Exit Codes

barbacane-control serve

Start the control plane HTTP server with PostgreSQL backend.

barbacane-control serve [OPTIONS]

Options

The --database-url can also be set via the DATABASE_URL environment variable.

Examples

# Start with explicit database URL
barbacane-control serve \
  --database-url postgres://postgres:password@localhost/barbacane \
  --listen 0.0.0.0:9090

# Using environment variable
export DATABASE_URL=postgres://postgres:password@localhost/barbacane
barbacane-control serve

# Skip migrations (not recommended)
barbacane-control serve \
  --database-url postgres://localhost/barbacane \
  --migrate=false

Database Setup

The control plane requires PostgreSQL 14+. Tables are created automatically via migrations:

# Create database
createdb barbacane

# Start server (migrations run automatically)
barbacane-control serve --database-url postgres://localhost/barbacane

API Endpoints

The server exposes a REST API for managing specs, plugins, artifacts, and projects:

Interactive API Documentation

The control plane includes interactive API documentation powered by Scalar. Access it at:

http://localhost:9090/api/docs

This provides a browsable interface for exploring and testing all API endpoints.

Full API Specification

Full OpenAPI specification: Control Plane OpenAPI

See the Control Plane Guide for detailed usage examples.