CLI Configuration

The Flagify CLI stores credentials under named profiles in ~/.flagify/config.json and resolves scope (workspace / project / environment) per invocation from a ranked list of sources. That makes it safe to share one machine between work and personal accounts, and to commit repo-level defaults without leaking tokens.

Global store — ~/.flagify/config.json

Schema v2, written atomically with 0600 on the file and 0700 on the directory.

{
  "version": 2,
  "current": "work",
  "accounts": {
    "work": {
      "accessToken": "eyJhbGci...",
      "refreshToken": "eyJhbGci...",
      "apiUrl": "https://api.flagify.dev",
      "consoleUrl": "https://console.flagify.dev",
      "user": { "id": "...", "email": "[email protected]", "name": "Jane Doe" },
      "defaults": {
        "workspace": "acme",
        "workspaceId": "01J5K8...",
        "project": "api",
        "projectId": "01J5KB...",
        "environment": "development"
      }
    },
    "personal": { "accessToken": "...", "refreshToken": "..." }
  },
  "bindings": {
    "/Users/jane/dev/acme-api": { "profile": "work" }
  }
}

Migration from v1

The first time a v2-aware CLI runs against a flat ~/.flagify/config.json, it migrates in place and writes a backup alongside — config.json.bak on first migration, then config.json.bak.YYYYMMDD-HHMMSS if a prior backup exists. Subsequent runs detect v2 and do not re-migrate.

Profiles

A profile is a locally-named identity. The names are yours — work, personal, client-acme, whatever fits. Every login creates or updates one profile, so you can sign into multiple accounts without logout/login loops.

flagify auth login --profile work

flagify auth list

flagify auth switch personal

flagify auth logout --profile work

flagify auth remove work

flagify auth rename work acme

See the Commands reference for the full auth and project subcommand tables.

Project file — .flagify/project.json

flagify init writes a committable project file that pins workspace, project, and environment for the repo. It never contains tokens.

{
  "version": 1,
  "workspaceId": "ws_01J...",
  "workspace": "acme",
  "projectId": "pr_01J...",
  "project": "api",
  "environment": "development",
  "preferredProfile": "work"
}

preferredProfile is a hint. Teammates with different local profile names can still use the same project file — the CLI falls through to a binding or the active profile when the hint does not match a local profile.

The walker searches for .flagify/project.json from the current directory upward, stopping before $HOME so it never interprets the global store as a project file.

Environment variables

FLAGIFY_* env vars override flags at the same precedence layer as the project file. Useful for CI, scripts, and one-shot invocations.

Precedence

Scope is resolved per field, not per document. The first source that has a value wins; IDs win over slugs within the same level.

1. CLI flag (--profile, --workspace-id, --workspace, --project-id, --project, --environment, --api-url).
2. Environment variable (FLAGIFY_*).
3. .flagify/project.json walked up from the current directory.
4. Local binding recorded in ~/.flagify/config.json → bindings.
5. The active profile’s defaults.
6. Built-in defaults (https://api.flagify.dev, etc.).

Profile picking (extra step)

When several profiles could match (repo with .flagify/project.json, multiple accounts in the store), the CLI picks in this order:

1. --profile <name>.
2. FLAGIFY_PROFILE.
3. Binding for the project file directory.
4. preferredProfile if that name exists locally.
5. current from the global store.
6. The sole profile, when exactly one exists.

If none of those produce a unique answer and more than one profile is signed in, the CLI errors with a message pointing at flagify auth list.

Inspecting the resolution

flagify status prints the resolved context and where each field came from.

flagify status
# Profile       work            (profile-default)
# User          Jane Doe <[email protected]>    (profile)
# Workspace     acme (ws_01J...)            (project-file)
# Project       api (pr_01J...)             (project-file)
# Environment   staging                     (flag)
# API URL       https://api.flagify.dev     (profile-default)
# Project file  /repo/.flagify/project.json
# Global store  ~/.flagify/config.json

flagify status --format json

--format json emits a sources map so scripts can assert on specific layers.

Setting defaults

Use the interactive pick commands when the CLI has API access:

flagify workspaces pick

flagify projects pick

flagify environments pick

Each command writes its selection to the active profile’s defaults in ~/.flagify/config.json. For repo-level scope, prefer the project file so teammates share the same setup:

flagify init --workspace-id ws_01J... --project-id pr_01J... --environment development

flagify project set environment staging

flagify config

flagify config

flagify config set api-url https://api.flagify.dev

flagify config set console-url https://console.flagify.dev

flagify config get api-url

Valid config set keys: api-url, console-url, workspace, project, environment. The last three still write to the active profile’s defaults for backwards compatibility — prefer flagify project set ... for repo-scoped changes.

Updating the CLI

npm

npm update -g @flagify/cli

Homebrew

brew upgrade flagify

Binary

Download the latest release from GitHub Releases.