> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Skill

> Manage Superflag feature flags using Claude Code or other AI agents

# Claude Code Skill

An optional skill that enables AI agents to manage your Superflag feature flags through natural language commands. Use it with Claude Code or any compatible AI coding assistant.

## Overview

The Superflag skill allows AI agents to execute CLI commands on your behalf, making it easy to create, update, and manage feature flags through conversation instead of typing commands manually.

The skill is available at [`.claude/skills/superflag`](https://github.com/superflag-sh/superflag-cli/tree/main/.claude/skills/superflag) in the superflag-cli repository.

## Installation

If you're using Claude Code in the superflag-mono directory, the skill is automatically available. For standalone usage:

1. Copy the skill directory to your project:
   ```bash theme={null}
   cp -r /path/to/superflag-mono/.claude/skills/superflag .claude/skills/
   ```

2. The skill will be available in your Claude Code session

## How It Works

When you ask Claude to manage your flags, the skill:

1. Executes CLI commands from the `superflag-cli` directory
2. Uses `bun run dev` to run commands in development mode
3. Maintains context throughout your session

All commands use the same Superflag CLI under the hood, so the behavior is identical to using the CLI directly.

## Example Usage

Here's how you can interact with the skill through natural language:

### Create a Feature Flag

**You:** "Create a new feature flag called 'dark-mode' set to false"

**Claude:** \[executes] `bun run dev flags upsert --key dark-mode --type bool --value false`

**Result:** ✓ Flag created

### Toggle a Flag

**You:** "Toggle the beta-features flag"

**Claude:** \[executes] `bun run dev flags toggle --key beta-features`

**Result:** ✓ Flag toggled

### Check Flag Value

**You:** "What's the current value of dark-mode?"

**Claude:** \[executes] `bun run dev get dark-mode`

**Result:** `false`

### Set Context

**You:** "Set the context to my-app production"

**Claude:** \[executes] `bun run dev use my-app production`

**Result:** ✓ Context set to my-app/production

## Available Operations

The skill can perform all CLI operations:

* **Set context** - Configure app and environment for subsequent commands
* **Create/update flags** - Add new flags or modify existing ones
* **Get flag values** - Check current flag values
* **Toggle boolean flags** - Flip true/false flags
* **Manage apps** - Create apps and list environments
* **Manage API keys** - Create and revoke SDK/client keys
* **Dump config** - Get full configuration as JSON

## Command Reference

Here are the commands the skill executes behind the scenes:

| Operation          | Command                                                             | Notes                                |
| ------------------ | ------------------------------------------------------------------- | ------------------------------------ |
| Set context        | `bun run dev use <app> <env>`                                       | Required before using quick commands |
| Get flag           | `bun run dev get <key>`                                             | Uses saved context                   |
| Set flag           | `bun run dev set <key> <value>`                                     | Uses saved context                   |
| Create/update flag | `bun run dev flags upsert --key <k> --type <t> --value <v>`         | Full syntax                          |
| Toggle flag        | `bun run dev flags toggle --app <app> --env <env> --key <key>`      | Boolean flags only                   |
| Dump config        | `bun run dev config`                                                | Outputs JSON                         |
| List apps          | `bun run dev apps list`                                             | Shows all your apps                  |
| Create app         | `bun run dev apps create <name>`                                    | Creates app with dev/staging/prod    |
| List keys          | `bun run dev keys list --app <app> --env <env>`                     | Shows API keys                       |
| Create key         | `bun run dev keys create --app <app> --env <env> --type <sdk\|pub>` | Generates new key                    |

## Flag Types

When creating flags, you can use these types:

| Type     | Example Value                       | Use Case                         |
| -------- | ----------------------------------- | -------------------------------- |
| `bool`   | `true`, `false`                     | Feature toggles, enable/disable  |
| `string` | `"dark"`, `"v2"`                    | Theme names, API versions, modes |
| `number` | `100`, `3.14`                       | Limits, timeouts, thresholds     |
| `json`   | `'{"theme":"dark","size":"large"}'` | Complex configuration objects    |

## Flag Visibility

All flags are available to both client and server keys:

```bash theme={null}
# Client-side flag (visible in browser/mobile app)
bun run dev flags upsert --key dark-mode --type bool --value true

# Another flag
bun run dev flags upsert --key api-url --type string --value https://api.example.com
```

All flags are returned by both `/api/v1/public-config` (client keys) and `/api/v1/config` (server keys). Server keys additionally receive rules and overrides.

## Context Management

The skill uses context saved to `~/.superflag/context.json`. Set it once per session:

```bash theme={null}
# Set context
bun run dev use my-app production

# Now quick commands work
bun run dev get feature-name
bun run dev set feature-name true
```

Context persists between commands in the same session.

## Authentication

The skill requires authentication. Make sure you're logged in:

```bash theme={null}
bun run dev status
# Output: Auth: Logged in as you@example.com
```

If not logged in:

```bash theme={null}
bun run dev login
```

Your credentials are stored in `~/.superflag/credentials.json`.

## Exit Codes

The skill respects standard CLI exit codes:

| Code | Meaning                                      |
| ---- | -------------------------------------------- |
| `0`  | Success                                      |
| `1`  | Error (invalid command, network issue, etc.) |
| `2`  | Not authenticated                            |
| `3`  | Resource not found                           |

## Troubleshooting

### Skill Not Available

If Claude doesn't recognize Superflag commands:

* Verify the skill directory exists at `.claude/skills/superflag/`
* Check that `SKILL.md` is present in the skill directory
* Restart your Claude Code session

### Authentication Errors

```
Error: Not authenticated
```

**Solution:** Log in with `bun run dev login`

### Context Not Set

```
Error: No context set. Use 'superflag use <app> <env>' first
```

**Solution:** Set context with `bun run dev use <app> <env>`

### Commands Not Found

```
Error: bun: command not found
```

**Solution:** Install Bun from [https://bun.sh](https://bun.sh) or use `npm` instead by modifying the skill commands

## Next Steps

<CardGroup cols={2}>
  <Card title="Commands Reference" icon="terminal" href="/cli/commands">
    Complete CLI command documentation
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Use the HTTP API directly
  </Card>
</CardGroup>