Documentation

CLI Configuration

reframe.config.json is a JSON file placed at your project root. When you run any CLI command, it searches up the directory tree from the current working directory until it finds this file, so a single config works across nested packages in a monorepo. Running reframe init creates the file automatically.

Configuration keys

Key	Type	Required	Default	Used by
`project`	string	Yes	—	`dev` `publish` `pull` `status`
`defaultBranch`	string	No	`"main"`	`dev` `status`
`output`	string	No	—	`dev`
`apiUrl`	string	No	`"https://studio.reframeui.app"`	all commands

project — Your design system's slug from the ReframeUI workspace. Every command uses this to identify which project to sync with.

defaultBranch — The branch the CLI targets when no --branch flag is passed.

output — Directory where pulled tokens are written. Used by reframe dev when watching for changes.

apiUrl — Base URL for all CLI requests. Override this for self-hosted or staging environments.

reframe.config.jsonjson

{
  "project": "my-design-system",
  "defaultBranch": "main",
  "output": "./tokens",
  "apiUrl": "https://studio.reframeui.app"
}

Environment variables

REFRAMEUI_API_KEY

Authenticates all CLI commands without a browser login. Set this in CI pipelines. Takes precedence over stored credentials from reframe login.

REFRAME_API_URL

Overrides the API base URL for all commands. Takes precedence over apiUrl in reframe.config.json. For self-hosted or staging use only.

Set REFRAMEUI_API_KEY as a repository secret, then reference it in your workflow:

GitHub Actions exampleyaml

name: Publish design system

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @reframeui/cli
      - run: reframe publish --bump patch
        env:
          REFRAMEUI_API_KEY: ${{ secrets.REFRAMEUI_API_KEY }}

Precedence

When the same setting can come from multiple places, the CLI resolves it in this order, highest priority first:

1CLI flags (for example, --out overrides output; --branch overrides defaultBranch)
2Environment variables (REFRAME_API_URL overrides apiUrl)
3reframe.config.json keys
4Built-in defaults

The project key has no CLI flag override. It is always read from reframe.config.json.

Config file discovery

The CLI calls findProjectRoot(), which walks up from the directory where you run the command, looking for reframe.config.json at each level. In a monorepo, place the file at the workspace root if all packages share the same project slug, or in each package directory if they point to different projects.

Monorepo with a shared configtext

my-monorepo/
├── reframe.config.json   ← single config for all packages
├── packages/
│   ├── web/
│   │   └── src/
│   └── mobile/
│       └── src/
└── apps/
    └── dashboard/

For flag-level documentation on each command, see the CLI Reference.