TokenLab CLI

Early-access command line client for pulling TokenLab export packages 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

Workspace owners and admins can disable TokenLab CLI access from the workspace Integrations page. The default is enabled, but when it is disabled, existing CLI device sessions cannot pull export packages or submit review-branch edits for that workspace. CLI 0.2.1 and newer report this as a direct workspace access message instead of a generic API error.

Commands

tokenlab login

Authenticates the CLI. By default this starts browser-based device login and saves the resulting device-session token in ~/.tokenlabrc. For advanced setups, you can pass a TokenLab bearer token directly:

tokenlab login <TOKEN>

tokenlab init

Runs the interactive setup wizard. It selects a workspace, project, library, export package, 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 package 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.

CLI 0.3.0 supports lossless DTCG value pushes for structured colors and units, semantic primitives (fontFamily, fontWeight, and strokeStyle), native composite values, whole-composite aliases, and top-level property references using DTCG $ref JSON Pointers. Native composites use the same validated per-field Core writes as the Web editor.

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.

Multi-export configuration is also supported:

export default {
  workspaceId: "workspace-id",
  workspaceName: "Workspace name",
  configType: "multi",
  exports: [
    {
      libraryId: "library-id",
      libraryName: "Library name",
      exportId: "export-id",
      exportName: "Export package name",
      outDir: "./tokens",
    },
  ],
  apiUrl: "https://tokenlab.design",
};

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

Authentication

The CLI reads bearer credentials in this order:

1. TOKENLAB_PAT (legacy environment variable name for direct token override)
2. ~/.tokenlabrc (written by tokenlab login)

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.