# struere keys

> Create, list, and revoke API keys from the command line

The `keys` command manages API keys for the current organization. Keys are scoped to a single environment (`development`, `production`, or `eval`) and authenticate requests to the Chat API, Data API, and CLI sync endpoints.

## Usage

```bash
bunx struere keys list
bunx struere keys create --name "my-app" --env development
bunx struere keys revoke sk_dev_a1b2
```

## Subcommands

### keys list

Lists all API keys for the current organization and environment.

```bash
bunx struere keys list [options]
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output raw JSON |

**Output:**

```
✓ Found 3 keys in development

  ID            Name             Prefix              Env          Created      Last used
  ────────────  ───────────────  ──────────────────  ───────────  ───────────  ───────────
  k57a1b2c3d4   my-app           sk_dev_a1b2****     development  2 days ago   1 hour ago
  k57e5f6g7h8   ci-pipeline      sk_dev_e5f6****     development  5 days ago   never
  k57i9j0k1l2   local-dev        sk_dev_i9j0****     development  1 week ago   3 days ago
```

The plaintext key is never returned by `list` — only the ID, name, masked prefix, environment, creation time, and last-used timestamp are displayed.

### keys create

Creates a new API key. The plaintext key is shown **once** at creation time and cannot be retrieved later — copy it into your secret store immediately.

```bash
bunx struere keys create [options]
```

| Flag | Description |
|------|-------------|
| `--name <name>` | Human-readable name for the key. Prompted if omitted |
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--confirm` | Skip the production confirmation prompt |
| `--json` | Output raw JSON (implies `--confirm`) |

Production keys require an interactive confirmation prompt unless `--confirm` or `--json` is set.

**Output:**

```
✓ API key created

  ID:      k57a1b2c3d4
  Name:    my-app
  Env:     development
  Key:     sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2

  Save this key now — it will not be shown again.
```

With `--json`:

```json
{
  "id": "k57a1b2c3d4",
  "name": "my-app",
  "environment": "development",
  "key": "sk_dev_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2",
  "createdAt": 1714780800000
}
```

### keys revoke

Hard-deletes an API key. The key cannot be reactivated — issued tokens stop working immediately.

```bash
bunx struere keys revoke <id-or-prefix> [options]
```

| Flag | Description |
|------|-------------|
| `--confirm` | Skip the confirmation prompt |
| `--json` | Output raw JSON (implies `--confirm`) |

The identifier is resolved against the current org's keys in this order:

1. Exact match on full key ID (`k57a1b2c3d4`)
2. Suffix match on key ID (`a1b2c3d4`)
3. Exact match on full prefix (`sk_dev_a1b2`)
4. Prefix-startswith match (`sk_dev_a1b2****` → `sk_dev_a1b2`)

If multiple keys match, the command exits with an error listing the candidates so you can re-run with a more specific identifier.

**Output:**

```
✓ Revoked key sk_dev_a1b2**** (my-app)
```

## Permissions

The `keys` command requires **organization admin** privileges. Non-admin members get a `403 Forbidden` response and cannot list, create, or revoke keys for the organization.

## Example: Vite SPA Frontend

Create a development key for a browser-based app that calls the Struere API directly via CORS:

```bash
bunx struere keys create --name "vite-frontend-dev" --env development
```

Copy the plaintext key into your local `.env`:

```
VITE_STRUERE_API_KEY=sk_dev_a1b2c3d4...
```

Use it from your Vite app via the [JavaScript client](../api/javascript-client):

```ts
import { StruereClient } from 'struere/client'

const struere = new StruereClient({
  apiKey: import.meta.env.VITE_STRUERE_API_KEY,
})

const reply = await struere.chat({
  agentSlug: 'support',
  message: 'Hi!',
})
```

For production, mint a separate key with `--env production` and store it in your hosting provider's secret manager — never check production keys into source control or expose them in client-side bundles for high-traffic apps.

## Error Cases

| Scenario | Behavior |
|----------|----------|
| Not an org admin | Exits with `403 Forbidden` |
| Identifier matches multiple keys | Exits with a list of candidates |
| Identifier matches no keys | Exits with `Key not found: <id-or-prefix>` |
| Production env without `--confirm` or `--json` | Prompts for confirmation |