Skip to main content

CLI

The Reforge CLI provides powerful tools for creating, modifying, and getting information about your configuration and flags. It also includes TypeScript code generation capabilities to provide type-safe access to your flags and configs.

Installation​

On a system with Node version 18+, run

npm install -g @reforge-com/cli

Authentication​

First, authenticate with Reforge:

reforge login

This will open your browser and authenticate you with Reforge. You can also use profiles to manage multiple workspaces:

reforge login --profile my-company

For additional details about authentication, profiles, and troubleshooting, see the login command documentation below.

Usage​

See reforge --help for all the available commands. reforge [COMMAND] --help will give you detailed information about a given command.

reforge is designed for humans first, but all commands support a --json flag to output JSON instead.

Global Flags​

These flags are available for all commands:

  • --verbose - Enable verbose output for debugging and detailed logging
  • --no-color - Disable colored output (useful for CI/CD or when piping output)
  • --interactive / --no-interactive - Force interactive mode on/off (defaults to auto-detect)
  • --json - Format output as JSON instead of human-readable text
  • --profile <name> - Use a specific authentication profile (available on API commands)

Examples:

# Get detailed logging information
reforge list --verbose

# Generate clean output for scripts
reforge get my.config --no-color --json

# Force non-interactive mode for automation
reforge create my.flag --type boolean-flag --value=true --no-interactive

# Use a specific profile
reforge list --profile production

TypeScript Code Generation​

⭐ Recommended: The generate command creates TypeScript definitions and type-safe clients for your Reforge configuration, providing autocomplete and type safety in your IDE.

Quick Start​

reforge generate

This generates TypeScript files in the generated/ directory:

  • reforge-client-types.d.ts - Type definitions for React/JavaScript
  • reforge-client.ts - Type-safe React/JavaScript client

Generate for Node.js​

reforge generate --targets node-ts

This generates:

  • reforge-server-types.d.ts - Type definitions for Node.js
  • reforge-server.ts - Type-safe Node.js client

Generate for Both Platforms​

reforge generate --targets react-ts,node-ts

Configuration File​

Create a reforge.config.json file in your project root to customize output:

{
  "outputDirectory": "src/generated",
  "targets": {
    "react-ts": {
      "outputDirectory": "src/client/generated",
      "declarationFileName": "reforge-types.d.ts",
      "clientFileName": "reforge-client.ts"
    },
    "node-ts": {
      "outputDirectory": "src/server/generated",
      "declarationFileName": "reforge-server-types.d.ts",
      "clientFileName": "reforge-server.ts"
    }
  }
}

Using Generated Types​

Once generated, import and use the type-safe clients:

// For React
import { useTypedReforge } from './generated/reforge-client';

// For Node.js
import { createTypedReforge } from './generated/reforge-server';

Commands​

generate-new-hex-key​

reforge generate-new-hex-key generates a cryptographically secure hex key suitable for encrypting config values with the --secret flag.

Example:

reforge generate-new-hex-key

This outputs a 64-character hex key like:

a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Use this key when creating or updating configs with encryption:

# Create an encrypted config using the generated key
reforge create my.secret --type string --value "sensitive data" --secret --secret-key-name "my-encryption-key"

Use cases:

  • Encrypting sensitive configuration values
  • Setting up encryption keys for different environments
  • Generating keys for config value protection

generate​

reforge generate creates TypeScript definitions and type-safe clients for your Reforge configuration, providing autocomplete and type safety in your IDE.

Options:

  • --targets <targets> - Specify target platforms (react-ts, node-ts)
  • --output-directory <dir> - Custom output directory
  • --profile <name> - Use specific profile

Examples:

# Generate for React/JavaScript (default)
reforge generate

# Generate for Node.js
reforge generate --targets node-ts

# Generate for both platforms
reforge generate --targets react-ts,node-ts

# Custom output directory
reforge generate --output-directory src/generated

This generates:

  • Type definitions (.d.ts files) with full TypeScript support
  • Type-safe client classes with camelCase method names
  • IntelliSense autocomplete for all configs and feature flags
  • Context-aware typing for better developer experience
info

💡 For detailed setup instructions, configuration options, and usage examples, see the TypeScript Code Generation section above. This includes information about configuration files, generated client usage, and integration with React and Node.js SDKs.

login​

reforge login authenticates you with Reforge using OAuth. This opens your browser to complete the authentication flow and stores tokens locally for subsequent CLI commands.

Options:

  • --profile <name> - Profile name to create or update (defaults to "default")
  • --json - Format output as JSON

Example:

reforge login
reforge login --profile production

Profiles allow you to manage multiple Reforge accounts or environments. Use the REFORGE_PROFILE environment variable or --profile flag to specify which profile to use.

logout​

reforge logout clears all stored authentication tokens from your local machine. After logging out, you'll need to run reforge login again to authenticate.

Example:

reforge logout

This affects all profiles and is useful for security, troubleshooting authentication issues, or switching accounts.

list​

reforge list shows keys for your configurations, feature flags, log levels, schemas, and segments. By default, all types are shown, but you can filter to specific types.

Options:

  • --configs - Include only configs
  • --feature-flags - Include only feature flags
  • --log-levels - Include only log levels
  • --schemas - Include only schemas
  • --segments - Include only segments
  • --json - Format output as JSON
  • --profile <name> - Use specific profile

Examples:

reforge list
reforge list --feature-flags
reforge list --configs --feature-flags
reforge list --json

When you specify one or more type flags, only those types are included in the output.

info​

reforge info NAME shows detailed information about a specific config, feature flag, or other resource, including current values across environments and recent evaluation statistics.

Example:

reforge info my.config.name

This displays:

  • Current values per environment
  • Links to the web console
  • Usage statistics over the last 24 hours
  • Evaluation breakdowns by value

interactive​

reforge interactive (or just reforge) launches an interactive CLI mode where you can browse and manage your resources through a menu-driven interface.

Example:

reforge
reforge interactive

This provides an easier way to explore your configs and flags without remembering specific command syntax.

override​

reforge override NAME allows you to override the value of a config or feature flag for your specific user/SDK key combination. This is especially helpful for testing different values without affecting other users.

Options:

  • --value <value> - Value to use for your override
  • --environment <env> - Environment to override in
  • --remove - Remove your existing override
  • --profile <name> - Use specific profile

Examples:

reforge override my.flag.name --value=true
reforge override my.config.name --value=42 --environment=staging
reforge override my.flag.name --remove

Overrides apply to any environment using an SDK key created by your Reforge user.

profile​

reforge profile manages authentication profiles and allows you to set the default profile for CLI operations.

Example:

reforge profile

This command helps you switch between different Reforge accounts or workspace configurations.

schema​

reforge schema NAME manages Zod schema definitions for your configs, providing type safety and validation.

Options:

  • --get - Get the current schema definition
  • --set-zod <schema> - Set a new Zod schema definition
  • --profile <name> - Use specific profile

Examples:

reforge schema my-schema --set-zod="z.object({url: z.string()})"
reforge schema my-schema --get

Schemas enable runtime validation and better TypeScript integration when using generated types.

serve​

reforge serve DATA-FILE starts a local server to serve a datafile, enabling offline development and testing with React/JavaScript clients.

Options:

  • --port <number> - Port to serve on (default: 3099)

Example:

reforge serve ./reforge.test.588.config.json --port=3099

This is useful for:

  • Local development without network connectivity
  • CI/CD pipelines that need consistent config data
  • Testing with specific datafile snapshots

Update your client to point to the local server:

endpoints: ["http://localhost:3099"]

workspace​

reforge workspace allows you to switch between different Reforge workspaces or display your current active workspace.

Example:

reforge workspace

This helps when you have access to multiple Reforge workspaces and need to switch contexts.

mcp​

reforge mcp configures the Reforge MCP (Model Context Protocol) server for AI assistants like Claude, Cursor, or other compatible editors.

Options:

  • --editor <type> - Editor to configure (claude-code, codeium)
  • --url <url> - Internal URL for testing

Examples:

reforge mcp
reforge mcp --editor cursor

This enables AI assistants to access your Reforge configuration data directly for better code assistance.

set-default​

reforge set-default NAME allows you to change the default value for an environment. Any rules defined for that environment will still apply; only the default is changed.

This can be particularly helpful for flipping a flag on or off for everyone.

Example:

reforge set-default my.flag.name --value=true --environment=staging

create​

reforge create NAME creates a new flag or config in Reforge. You can use this to create basic values, encrypted secrets, or values provided by ENV vars.

Supported types: boolean-flag, boolean, string, double, int, string-list, json, duration, int-range, bytes

Examples:

# Basic types
reforge create my.new.string --type string --value="hello world"
reforge create my.feature --type boolean-flag --value=true
reforge create my.timeout --type int --value=30
reforge create my.price --type double --value=19.99

# Complex types
reforge create my.tags --type string-list --value="tag1,tag2,tag3"
reforge create my.config --type json --value='{"key": "value"}'
reforge create my.duration --type duration --value="30s"
reforge create my.range --type int-range --value="1-100"
reforge create my.size --type bytes --value="1GB"

# Encrypted values (requires string type)
reforge create my.secret --type string --value="sensitive data" --secret

# Environment variable sourced
reforge create my.db.url --type string --env-var=DATABASE_URL

# Confidential (non-encrypted) values
reforge create my.api.key --type string --value="key123" --confidential

Encryption vs Confidential:

  • --secret: Encrypts the value, requires decryption key
  • --confidential: Marks value as sensitive but doesn't encrypt (useful for display purposes)
  • --secret implies --confidential, so you don't need both

download​

reforge download downloads a datafile for a given environment. Datafiles are helpful for offline testing, CI/CD pipelines, and running your own JS/React endpoint with the serve command.

Options:

  • --environment <env> - Environment to download (required)
  • --json - Output JSON format

Examples:

# Basic download
reforge download --environment=test

# Download for different environments
reforge download --environment=production
reforge download --environment=staging

CI/CD Integration:

# In your CI pipeline, download configs for testing
reforge download --environment=test

# Use with serve for integration tests
reforge serve reforge.test.588.config.json --port=3099 &
PID=$!
npm run test:integration
kill $PID

Offline Development Setup:

# Download configs for offline work
reforge download --environment=development

# Start local server for offline development
reforge serve reforge.development.589.config.json

The downloaded file can be used with the serve command or for snapshot testing in your application.

get​

reforge get NAME will give you the value for a config in the environment tied to your SDK key.

Example:

reforge get aws.bucket

Interpolating a value from Reforge​

Since the CLI is a well-behaved citizen of the command line, you can use it to compose other commands.

Here's an example command to download a file from s3 using the aws cli. Reforge values are interpolated for the aws key and bucket name.

aws s3api get-object \
  --bucket $(reforge get aws.bucket) \
  --key $(reforge get aws.db.backup.filename) \
  db.tgz

As you'd expect, you can similarly use reforge in a pipeline with xargs and similar.

info​

reforge info NAME will show details about an item in Reforge. Example output:

reforge info aws.bucket

https://app.cloud/account/projects/XYZ/configs/aws.bucket

- Default: false
- Staging: true
- Production: [see rules] https://app.cloud/account/projects/XYZ/configs/aws.bucket?environment=588

Evaluations over the last 24 hours:

Production: 34,789
- 33% - false
- 67% - true

Staging: 17,138
- 100% - true

Development: 7
- 100% - false

list​

reforge list will show the names of items in your Reforge account. You can pass flags to filter this to only show items of a specific type (e.g. segments).

override​

reforge override lets you override the value for a config or feature flag for your reforge.com user. This is especially helpful for testing both sides of a feature flag.

Are you using a backend key for your server code and a frontend key for your UI? No problem; this override will apply to any environment using an SDK key created by your reforge.com user.

Example:

reforge override my.flag.name --value=true

serve​

reforge serve will start a local server to serve up a local datafile that React and JS clients can talk to. See reforge download for more.

reforge serve reforge.test.588.config.json
# Server is listening on 3099. Press ctrl-c to stop.

Example Dockerfile

FROM node:20
WORKDIR /app
RUN npm i -g @reforge-com/cli
COPY reforge.Production.589.config.json /app
ENV REFORGE_LOCAL_ONLY=true
EXPOSE 9898
CMD reforge serve reforge.Production.589.config.json --port=9898

Troubleshooting​

Common Issues​

Authentication Problems:

# Clear authentication and re-login
reforge logout
reforge login

# Use specific profile
reforge login --profile production

Configuration Generation Issues:

# Generate with verbose output to see detailed logs
reforge generate --verbose

# Check if config file exists and is valid JSON
cat reforge.config.json | jq .

MCP Configuration Issues:

# Verify editor configuration was created
# For VS Code/Cursor:
cat ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

# For Claude Desktop:
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

Network/API Issues:

# Test connectivity with verbose output
reforge list --verbose

# Check API endpoint override
echo $REFORGE_API_URL_OVERRIDE

Environment Variables​

  • REFORGE_API_URL_OVERRIDE - Override the default API URL
  • REFORGE_PROFILE - Set default profile to use
  • NO_COLOR - Disable colored output
  • REFORGE_LOCAL_ONLY - Use only local datafiles (for serve command)