TokenLab CLI

Early-access command line client for pulling TokenLab export pipelines into a local project and submitting local token edits back to TokenLab review branches.

Install

npm install -g tokenlab

The package exposes two binaries:

tokenlab --help
tl --help

Commands

tokenlab login

Authenticates the CLI. By default this starts the browser-based device flow and saves the resulting token in ~/.tokenlabrc. You can also pass a Personal Access Token directly:

tokenlab login <TOKEN>

tokenlab init

Runs the interactive setup wizard. It selects a workspace, project, library, export pipeline, and output directory, then writes tokenlab.config.ts. If no local credential exists yet, init starts the same browser-based device flow as tokenlab login before loading your workspaces.

tokenlab pull

Executes the configured export pipeline and writes the generated files to the configured output directory. The command also writes .tokenlab/state.json and sidecar sourcemap files when the server returns sourcemaps. It also stores local baselines under .tokenlab/baselines/ so tokenlab push can detect which generated token values changed since the last pull.

When output files already exist, pull overwrites them with the latest export output. This keeps the generated file and its sidecar sourcemap unambiguous so push can map local edits back to the correct TokenLab source. --force is accepted for compatibility, but overwrite is the default behavior.

tokenlab push

Reads local sourcemap-backed edits, creates a new CLI-origin branch in TokenLab, writes the changed token values to that branch, and opens a branch-to-main review request. Push is supported for export packages whose source is the Working Draft. Export packages pinned to a release are read-only for CLI push and will be reported as such.

Help And Version

tokenlab --help
tokenlab <command> --help
tokenlab --version
tokenlab -v
tokenlab -V

tokenlab pull -v is reserved for verbose logging on that command.

Configuration

tokenlab.config.ts is loaded from the current working directory. A single export configuration looks like this:

export default {
  workspaceId: "workspace-id",
  workspaceName: "Workspace name",
  projectId: "project-id",
  projectName: "Project name",
  configType: "single",
  libraryId: "library-id",
  libraryName: "Library name",
  exportId: "export-id",
  exportName: "Export package name",
  outDir: "./tokens",
  apiUrl: "https://tokenlab.design",
};

The readable *Name fields are informational only; IDs remain the authoritative links to TokenLab resources.

The API URL can also be overridden with TOKENLAB_API_URL or --apiUrl.

Authentication

The CLI reads credentials in this order:

1. TOKENLAB_PAT
2. ~/.tokenlabrc

Run tokenlab login again to refresh the local credential. You can also run tokenlab init in a fresh project; it will start browser login automatically when no local credential is available.