@traffical/cli

Config-as-code CLI for Traffical - manage your feature flags and experimentation parameters in version-controlled YAML files.

Installation

# Install globally
npm install -g @traffical/cli

# Or use via npx
npx @traffical/cli init

Quick Start

# Initialize in your project
traffical init --api-key <your-api-key>

# Push local changes to Traffical
traffical push

# Pull updates from Traffical
traffical pull

# Bidirectional sync
traffical sync

What init Creates

Running traffical init creates a .traffical/ directory with:

.traffical/
├── config.yaml      # Main configuration file
├── AGENTS.md        # AI agent integration guide
└── templates/       # Framework-specific code templates
    ├── feature-flag.tsx
    ├── ab-test.tsx
    └── server.ts

The CLI automatically detects your framework (React, Next.js, Svelte, SvelteKit, Vue, Nuxt, Node.js) and generates appropriate templates.

Commands

| Command | Description | |---------|-------------| | init | Initialize Traffical in a project, creates .traffical/ directory | | push | Push local config to Traffical (validates first) | | pull | Pull synced parameters from Traffical to local config | | sync | Bidirectional sync (local wins policy) | | status | Show current sync status | | import <key> | Import dashboard parameters (supports wildcards: ui.*, *.enabled) | | integrate-ai-tools | Add Traffical references to AI tool config files |

Sync Behavior

The CLI uses a "local wins" policy for the sync command:

1. Validates your local config first (catches errors before any network calls)
2. Pushes your local parameters and events to Traffical (your edits take precedence)
3. Adds new parameters and events from Traffical that you don't have locally
4. Warns about conflicts (but your local version is used)

This matches the Git workflow where your local file is the source of truth. If you want to overwrite local changes with remote values, use traffical pull explicitly.

Example Workflow

# Edit config locally
vim .traffical/config.yaml

# Sync: your changes are pushed, new remote params/events are added
traffical sync

# If you want remote values to overwrite local:
traffical pull

Config File Format

Parameters are organized by namespace. The main namespace lives under the top-level parameters: key, while other namespaces are grouped under namespaces: using their local key (without the namespace prefix).

# .traffical/config.yaml
version: "1.0"
project:
  id: proj_xxx
  orgId: org_xxx

# "main" namespace parameters (no prefix)
parameters:
  global_feature_enabled:
    type: boolean
    default: false
    description: Kill-switch for global feature

# Other namespaces — keys are local (prefix is implicit)
namespaces:
  checkout:
    parameters:
      button.color:           # full key: checkout.button.color
        type: string
        default: "#FF6600"
        description: Primary CTA button color
  catalog:
    parameters:
      ranking_algo:            # full key: catalog.ranking_algo
        type: string
        default: "default"
        description: Which ranking algorithm to use
        constraints:
          allowedValues: ["default", "popularity", "random"]
  pricing:
    parameters:
      discount.enabled:        # full key: pricing.discount.enabled
        type: boolean
        default: false

events:
  purchase:
    valueType: currency
    unit: USD
    description: User completes a purchase

  add_to_cart:
    valueType: count
    description: User adds item to cart

Backwards compatibility: The flat format (all parameters under parameters: with an explicit namespace field) is still accepted on read. The CLI normalizes it internally. On write (pull/sync), the grouped format above is always produced.

Parameter Types

| Type | Default Value | |------|---------------| | string | Any string | | number | Any number | | boolean | true or false | | json | Object or array |

Parameter Constraints

Parameters can have optional constraints that restrict their values. Constraints are synced to Traffical and shown in the dashboard UI.

namespaces:
  catalog:
    parameters:
      ranking_algo:
        type: string
        default: "default"
        description: Which ranking algorithm to use
        constraints:
          allowedValues: ["default", "popularity", "random"]
  pricing:
    parameters:
      discount_pct:
        type: number
        default: 10
        constraints:
          min: 0
          max: 100
  checkout:
    parameters:
      promo_code:
        type: string
        default: ""
        constraints:
          pattern: "^[A-Z0-9]{4,10}$"

| Constraint | Applies To | Description | |------------|-----------|-------------| | allowedValues | string, number | Restrict to specific values (enum-like) | | min | number | Minimum allowed value | | max | number | Maximum allowed value | | pattern | string | Regex pattern to validate values |

When allowedValues are set, the Traffical dashboard renders a dropdown selector instead of a free-text input for default values and policy overrides.

Events

Events define the metrics you want to track in your experiments and analytics. They are synced to Traffical alongside your parameters.

# .traffical/config.yaml
version: "1.0"
project:
  id: proj_xxx
  orgId: org_xxx

parameters:
  # ... main namespace parameters ...

namespaces:
  # ... other namespace parameters ...

events:
  purchase:
    valueType: currency
    unit: USD
    description: User completes a purchase

  add_to_cart:
    valueType: count
    description: User adds item to cart

  checkout_started:
    valueType: boolean
    description: User initiates checkout

  conversion_rate:
    valueType: rate
    unit: percent
    description: Percentage of visitors who convert

Event Value Types

| Value Type | Use Case | Example | |------------|----------|---------| | currency | Monetary values (revenue, order value) | Purchase amount in USD | | count | Numeric counts (clicks, items, views) | Items added to cart | | rate | Percentages or ratios | Conversion rate | | boolean | Binary events (happened or not) | Checkout started |

Event Properties

| Property | Required | Description | |----------|----------|-------------| | valueType | Yes | Type of value: currency, count, rate, or boolean | | unit | No | Unit for the value (e.g., USD, items, percent) | | description | No | Human-readable description of what the event tracks |

Validation

The CLI validates your config against a JSON Schema before pushing:

• Required fields (version, project.id, project.orgId)
• Type consistency (e.g., type: boolean must have a boolean default)
• ID format (proj_* and org_* prefixes)
• Event definitions (valid valueType values)

# Validation happens automatically on push/sync
traffical push

# Example error output
✗ Invalid config file

Errors:
  - parameters.my_flag.default: must be boolean

AI Tool Integration

The CLI can automatically add Traffical references to AI coding tool configuration files:

# Scan and update AI tool files
traffical integrate-ai-tools

# Or auto-confirm without prompting
traffical integrate-ai-tools --yes

Supported files:

• CLAUDE.md (Claude Code)
• .cursorrules (Cursor)
• .github/copilot-instructions.md (GitHub Copilot)
• .windsurfrules (Windsurf)

This helps AI agents understand that your project uses Traffical and how to properly use feature flags and A/B tests.

Global Options

-p, --profile <name>   # Use a specific profile from ~/.trafficalrc
-c, --config <path>    # Path to config file (default: .traffical/config.yaml)
-b, --api-base <url>   # API base URL (for self-hosted instances)
-j, --format <format>  # Output format: human (default) or json
-n, --dry-run          # Validate and preview changes without applying (push/sync)

JSON Output

For scripting and CI/CD integration, use --format json to get machine-readable output:

# Get status as JSON
traffical status --format json

# Example output
{
  "project": { "id": "proj_xxx", "name": "My Project" },
  "org": { "id": "org_xxx", "name": "My Org" },
  "synced": [{ "key": "feature.enabled", "type": "boolean" }],
  "dashboardOnly": [],
  "localOnly": [],
  "hasDrift": false
}

Environment Variables

For CI/CD pipelines, credentials can be provided via environment variables:

| Variable | Description | |----------|-------------| | TRAFFICAL_API_KEY | API key for authentication | | TRAFFICAL_API_BASE | API base URL (optional, for self-hosted) |

Priority order (highest to lowest):

1. Command-line flags (--api-key, --api-base)
2. Environment variables (TRAFFICAL_API_KEY, TRAFFICAL_API_BASE)
3. Profile from ~/.trafficalrc

Exit Codes

For scripting and CI/CD integration:

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Validation error (invalid config file) | | 2 | Authentication error (invalid or missing API key) | | 3 | Network/API error | | 10 | Config drift detected (status command) | | 11 | Experiment needs attention |

Profiles

API keys are stored in ~/.trafficalrc:

default_profile: default
profiles:
  default:
    api_key: tk_xxx
  staging:
    api_key: tk_yyy
    api_base: https://staging.traffical.io

Use with: traffical push --profile staging

CI/CD Integration

The CLI is designed for CI/CD pipelines. Use environment variables for credentials and --dry-run for validation.

Sync on Merge to Main

Use case: Automatically push parameter changes to Traffical when code is merged to main. This ensures your production parameters stay in sync with your codebase.

# .github/workflows/traffical-sync.yml
name: Sync Traffical Config

on:
  push:
    branches: [main]
    paths:
      - '.traffical/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Traffical CLI
        run: npm install -g @traffical/cli
      
      - name: Push to Traffical
        run: traffical push
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY }}

Validate on Pull Request

Use case: Catch configuration errors before they're merged. The --dry-run flag validates the config and shows what would change without actually modifying anything.

# .github/workflows/traffical-validate.yml
name: Validate Traffical Config

on:
  pull_request:
    paths:
      - '.traffical/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Traffical CLI
        run: npm install -g @traffical/cli
      
      - name: Validate Config (Dry Run)
        run: traffical push --dry-run
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY }}

Drift Detection with JSON Output

Use case: Detect when someone changes parameters directly in the Traffical dashboard without updating the config file. Use JSON output for easier parsing.

# .github/workflows/traffical-drift.yml
name: Check Traffical Drift

on:
  schedule:
    - cron: '0 9 * * *'  # Daily at 9am UTC

jobs:
  check-drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Traffical CLI
        run: npm install -g @traffical/cli
      
      - name: Check for Drift
        id: status
        run: |
          STATUS=$(traffical status --format json)
          echo "$STATUS"
          DRIFT=$(echo "$STATUS" | jq '.hasDrift')
          echo "drift=$DRIFT" >> $GITHUB_OUTPUT
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY }}
      
      - name: Create Issue on Drift
        if: steps.status.outputs.drift == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '⚠️ Traffical config drift detected',
              body: 'Parameters exist locally that are not synced to Traffical.\n\nRun `traffical status` locally to see details, then run `traffical push` to sync.'
            })

Environment-Specific Deploys

Use case: Deploy different parameter configurations to staging and production environments, each with their own Traffical project.

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main, staging]

jobs:
  sync-traffical:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Traffical CLI
        run: npm install -g @traffical/cli
      
      - name: Sync to Staging
        if: github.ref == 'refs/heads/staging'
        run: traffical push
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY_STAGING }}
      
      - name: Sync to Production
        if: github.ref == 'refs/heads/main'
        run: traffical push
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY_PROD }}

Learn More

• Config-as-Code Documentation
• Parameter Schema Reference