Unleash CLI

AI-friendly CLI for managing Unleash feature flags. Built with Bun and TypeScript.

Installation

npm install -g @onmyway133/unleash-cli

Or with Bun:

bun add -g @onmyway133/unleash-cli

Configuration

On first use, run the setup wizard:

unleash config setup

You'll be prompted for your Unleash URL and API token (Admin token or Personal Access Token).

Config is saved to ~/.config/unleash-cli/config.json.

Environment variables

Override config at any time with environment variables:

| Variable | Description | |---|---| | UNLEASH_URL | Unleash instance URL (e.g. https://unleash.example.com) | | UNLEASH_TOKEN | API token (Admin or Personal Access Token) |

UNLEASH_URL=https://unleash.example.com UNLEASH_TOKEN=my-token unleash flags list --project default

Other config commands

unleash config show          # Show current config (token masked)
unleash config set url https://unleash.example.com
unleash config set token my-new-token
unleash config clear         # Remove all stored config
unleash config path          # Print config file path

Usage

Global options

Every command supports:

| Option | Description | |---|---| | --json | Output as JSON (ideal for AI agents and automation) | | --quiet | Suppress informational output | | -V, --version | Print version |

Projects

unleash projects list
unleash projects get my-project
unleash projects create my-project "My Project" --description "Optional description"
unleash projects delete my-project

Feature Flags

# List / inspect
unleash flags list --project default
unleash flags get my-flag --project default

# Create / update
unleash flags create my-flag --project default --type release --description "My flag"
unleash flags update my-flag --project default --description "Updated"

# Toggle in an environment
unleash flags enable  my-flag --project default --env production
unleash flags disable my-flag --project default --env production

# Lifecycle
unleash flags archive   my-flag --project default
unleash flags unarchive my-flag
unleash flags stale     my-flag --project default
unleash flags stale     my-flag --project default --unmark

Flag types: release, experiment, operational, kill-switch, permission

Environments (per flag)

unleash environments list --project default --flag my-flag
unleash environments enable  --project default --flag my-flag --env staging
unleash environments disable --project default --flag my-flag --env staging

Strategies

unleash strategies list --project default --flag my-flag --env production

# Add the default (always-on) strategy
unleash strategies add --project default --flag my-flag --env production --name default

# Add a gradual rollout strategy
unleash strategies add \
  --project default --flag my-flag --env production \
  --name gradualRollout \
  --parameters '{"rollout":"50","stickiness":"default","groupId":"my-flag"}'

# Add a strategy with constraints
unleash strategies add \
  --project default --flag my-flag --env production \
  --name default \
  --constraints '[{"contextName":"userId","operator":"IN","values":["123","456"]}]'

unleash strategies update <strategyId> --project default --flag my-flag --env production --name gradualRollout --parameters '{"rollout":"75","stickiness":"default","groupId":"my-flag"}'
unleash strategies delete <strategyId> --project default --flag my-flag --env production

Segments

unleash segments list
unleash segments get 1

unleash segments create beta-users \
  --constraints '[{"contextName":"userId","operator":"IN","values":["1","2"]}]'

unleash segments update 1 --name beta-users --constraints '...'
unleash segments delete 1

Variants

Variants use a bulk-replace model: variants update replaces all variants at once.

unleash variants list --project default --flag my-flag

unleash variants update \
  --project default --flag my-flag \
  --data '[{"name":"red","weight":500,"weightType":"variable"},{"name":"blue","weight":500,"weightType":"variable"}]'

Context Fields

unleash context list
unleash context get userId

unleash context create region --description "User region" --stickiness
unleash context create plan --legal-values '[{"value":"free"},{"value":"pro"},{"value":"enterprise"}]'

unleash context update region --description "Updated description"
unleash context delete region

Global Environments

unleash envs list
unleash envs          # same as list

Health & Status

unleash health        # Quick health check
unleash status        # Full status report: projects, flag counts, health per project

AI Agent Integration

All commands support --json for machine-readable output. Errors also return JSON when using --json, making it safe to use in automated pipelines.

Discover all commands

unleash usage          # Returns full JSON schema of all commands and options

JSON output examples

# List flags as JSON
UNLEASH_TOKEN=my-token unleash --json flags list --project default

# Check health as JSON
unleash --json health

# Error response shape
# { "error": "Not Found", "code": "NOT_FOUND", "statusCode": 404 }

Using env vars (no config file needed)

UNLEASH_URL=https://unleash.example.com \
UNLEASH_TOKEN=my-token \
unleash --json flags list --project default

License

MIT