CLI

@traffical/cli manages your Traffical configuration as code. You define parameters, context attributes, events, and metrics in a .traffical/ directory, version-control them alongside your application, and sync with the platform with push, pull, and status.

Why config-as-code

Single source of truth — parameter and event definitions live in your repo, reviewed in pull requests like any other code.
No drift — definitions you push become synced: read-only in the dashboard, so the repo and the platform can’t disagree.
Typed events and context — generate TypeScript types from your event schemas and attribute registry so invalid track() calls and misspelled context keys fail at compile time.
CI-enforceable — traffical status exits non-zero on drift, so you can gate merges on the repo and platform being in sync.

Policies, allocations, and lifecycle decisions still live in the dashboard — the CLI owns the definitions, not the rollout state.

Installation

npm install -g @traffical/cli
# or run without installing
bunx @traffical/cli init

Requires Node.js 18+.

Quickstart

Initialize

From your project root, scaffold the .traffical/ directory and link a project:

traffical init

init logs you in, lets you pick an org and project, writes config.yaml and project.yaml, creates a public SDK key, and drops example code for your framework.

Edit your config

Add or change parameters, attributes, and events in .traffical/config.yaml. See the configuration file reference for every field.

Push to Traffical

traffical push

Check for drift

traffical status

Authentication

For interactive use, log in once with the browser-based device flow:

traffical login

This opens your browser, asks you to confirm a code, and stores a session at ~/.config/traffical/auth.json (mode 0600). The session holds a refresh token and renews access tokens automatically, so you rarely log in again.

traffical whoami            # show the active identity and linked project
traffical whoami --verify   # live-check the session against the server
traffical logout            # remove the local session

whoami without --verify reports the cached session. A cached session can still be reported as authenticated after it has ended server-side — use --verify when you need a definitive answer.

Credential precedence

The CLI resolves a bearer token in this order:

--api-key <key> on the command line
TRAFFICAL_API_KEY environment variable (org-scoped key — the CI path)
TRAFFICAL_API_TOKEN environment variable (pre-minted JWT, for agents)
The device-flow session from traffical login
A legacy ~/.trafficalrc profile (--profile <name>) — deprecated

For CI, set TRAFFICAL_API_KEY and skip login entirely.

# Headless / agent login with a pre-minted token
traffical login --token "$JWT"
# Print the URL + code instead of opening a browser
traffical login --no-browser

Selecting a project

A repo is linked to exactly one Traffical project, recorded in .traffical/project.yaml.

traffical link                      # interactive org + project picker
traffical link --org acme --project marketplace
traffical unlink                    # remove the link (leaves config.yaml)

When a flag is omitted, the CLI prompts: a select list for ≤10 options, a search box beyond that. Pass --force to re-link a repo that’s already linked. Manage orgs and projects directly:

traffical org list                  # orgs you belong to
traffical org use <key>             # default org for commands that need one

traffical project list              # projects in the active org
traffical project create <name> --link
traffical project use <key>         # alias of `link --project <key>`

Syncing configuration

status — see the difference

traffical status

Shows what’s synced, what has local changes to push, and what exists only in the dashboard. Exits with code 10 when there’s drift, so it doubles as a CI check.

Connected to: Acme/Marketplace (proj_Ab3xYz9k)

Parameters
  Synced: 7 parameters
  Dashboard-only: 2 parameters
    ui.sees-feature-y (created 5/20/2026)

Events
  Synced: 4 events

Metrics
  Dashboard-only: 4 metrics

Attributes
  Synced: 3 attributes
    device_type (string/enum)
    cart_value (number)
    user_id (string)
  Dashboard-only: 1 attribute
    plan (string/enum) created 2 days ago

The Attributes section lists user-managed attributes only; $-prefixed system attributes are never shown. Local-only attributes (in the file, not yet pushed) count as drift.

push — repo → Traffical

traffical push [--dry-run] [--prune]

Creates new definitions and updates existing synced ones. Pushed definitions become read-only in the dashboard. Attributes go first — before parameters, property groups, events, and metrics — so policies validated later in the run already see the registry.

--dry-run — validate and print the diff without applying.
--prune — archive synced parameters and attributes that have been removed from the file. Without it, removals stay on the platform. An attribute still referenced by a policy condition is skipped — reported, not archived — so pruning never breaks a running policy. A file with no attributes: block at all leaves the project’s attributes alone.

pull — Traffical → repo

traffical pull [--include-types]

Downloads synced parameters, events, and property groups into config.yaml. Dashboard-only parameters, events, and metrics stay in the dashboard until you import them; attributes are the exception — every active user-managed attribute is written, synced or not. System attributes ($-prefixed) are never written. --include-types runs generate-types afterwards.

sync — both directions

traffical sync [--all] [--dry-run] [--prune]

Pushes local changes and pulls new remote definitions in one pass. On conflict, local wins. --all syncs every config file in the repo.

Importing dashboard definitions

Definitions created in the dashboard are dashboard-only until you adopt them into code:

traffical import param ui.accent_color   # one parameter
traffical import param 'ui.*'            # wildcard
traffical import metrics --all           # all metrics → metrics.yaml
traffical import metrics add_to_cart_rate

Type-safe events

Generate TypeScript types from your event definitions so invalid event names and properties become compile errors:

traffical generate-types          # writes .traffical/traffical.generated.ts
traffical generate-types -o src/traffical.generated.ts

This emits a TrafficalEventProperties map — event name → typed property shape. Wrap your client’s track:

import type { TrafficalEventProperties } from "./traffical.generated";

type TypedTrack = <E extends keyof TrafficalEventProperties>(
  event: E,
  options: { unitKey: string; properties?: TrafficalEventProperties[E]; decisionId?: string }
) => void;

export const track = traffical.track.bind(traffical) as TypedTrack;

track("add_to_cart", { unitKey: "user_789", properties: { product_id: "p_1" } }); // ✅
track("add_to_cart", { unitKey: "user_789", properties: { unknown: true } });      // ❌ compile error

Run it after every pull (or in CI) to keep types in sync. See Type-safe events for the full flow.

Typed context

When the repo is linked and you are logged in, generate-types also reads the project’s attribute registry and emits a TrafficalContext interface plus a TrafficalAttributeKey union in the same file:

export interface TrafficalContext {
  /** identifier — may serve as a unit or entity key */
  "$unit_key"?: string;
  cart_value?: number;
  /** Client form factor */
  device_type?: "mobile" | "desktop";
  /** timestamp — epoch milliseconds */
  signed_up_at?: number;
  [key: string]: unknown;
}

export type TrafficalAttributeKey = "$unit_key" | "cart_value" | "device_type" | "signed_up_at";

One optional property per active attribute, system attributes included; $-prefixed and dotted keys are quoted.
string → string, enum → a union of its values, number → number, boolean → boolean, timestamp → number (epoch milliseconds).
The trailing index signature keeps unregistered keys compiling; TrafficalAttributeKey is the union of registered keys only.

import type { TrafficalContext } from "./.traffical/traffical.generated";

const context = { device_type: "mobile", cart_value: 42 };
const decision = traffical.decide(context satisfies TrafficalContext, defaults);

The summary line reports Attributes: N. If the repo is not linked, you are not logged in, or the attribute registry is unavailable on the server, the context types are left out and the summary prints a note instead of failing — the parameter and event types are still generated.

CI/CD integration

# .github/workflows/traffical.yml
name: Traffical
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bunx @traffical/cli status   # exits 10 on drift
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY }}

# .github/workflows/traffical-sync.yml
name: Traffical sync
on:
  push:
    branches: [main]
    paths: [".traffical/**"]
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bunx @traffical/cli push --prune
        env:
          TRAFFICAL_API_KEY: ${{ secrets.TRAFFICAL_API_KEY }}

Command reference

Command	Description
`login`	Authenticate via browser (OAuth device flow).
`logout`	Remove the local session.
`whoami`	Show the active identity and linked project.
`init`	Log in, link a project, and scaffold `.traffical/`.
`link` / `unlink`	Link the repo to a project / remove the link.
`org list` / `org use`	List orgs / set the default org.
`project list` / `create` / `use`	Manage projects in the active org.
`status`	Show drift between local and remote.
`push`	Send local definitions to Traffical.
`pull`	Pull synced definitions into the repo.
`sync`	Bidirectional sync (local wins on conflict).
`import param` / `import metrics`	Adopt dashboard definitions into code.
`generate-types`	Generate TypeScript types from parameter and event definitions, plus `TrafficalContext` from the attribute registry.

Global options

Option	Description
`-c, --config <path>`	Path to the config file (default `.traffical/config.yaml`).
`-b, --api-base <url>`	Override the API endpoint.
`-j, --format <fmt>`	`human` (default) or `json`.
`-q, --quiet`	Suppress non-essential output.
`-p, --profile <name>`	Legacy `~/.trafficalrc` profile (deprecated).

Environment variables: TRAFFICAL_API_KEY, TRAFFICAL_API_TOKEN, TRAFFICAL_API_BASE.

Exit codes

Code	Meaning
`0`	Success.
`1`	Validation error in config.
`2`	Authentication error (not logged in / token invalid).
`3`	Network or API error.
`4`	Not linked (no `project.yaml`).
`10`	Drift detected (`status`).
`11`	Policy needs attention.

Next steps

Configuration file

Every field in config.yaml, project.yaml, and metrics.yaml.

Parameters

Typed values with defaults.

Type-safe events

Codegen, SDK typing, and dev-mode validation.

Quickstart

Resolve a parameter and track an event.

Getting started

Core concepts

Experimentation

Statistics

Guides

Dashboard

Governance

Warehouse connectors

Developer tools

Reference

Why config-as-code

Installation

Quickstart

Authentication

Credential precedence

Selecting a project

Syncing configuration

Importing dashboard definitions

Type-safe events

Typed context

CI/CD integration

Command reference

Global options

Exit codes

Next steps

Configuration file

Parameters

Type-safe events

Quickstart

​Why config-as-code

​Installation

​Quickstart

​Authentication

​Credential precedence

​Selecting a project

​Syncing configuration

​Importing dashboard definitions

​Type-safe events

​Typed context

​CI/CD integration

​Command reference

​Global options

​Exit codes

​Next steps

Configuration file

Parameters

Type-safe events

Quickstart

Why config-as-code

Installation

Quickstart

Authentication

Credential precedence

Selecting a project

Syncing configuration

Importing dashboard definitions

Type-safe events

Typed context

CI/CD integration

Command reference

Global options

Exit codes

Next steps