# Workflow Commands

CLI commands for development workflow.

Source: https://keyenv.dev/docs/cli/workflow/

Commands that integrate with your development workflow.

## run

Run a command with secrets injected as environment variables.

```bash
keyenv run [OPTIONS] -- <COMMAND>
```

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |

### Examples

```bash
# Run npm start with secrets
keyenv run -- npm start

# Run with production secrets
keyenv run -e production -- node server.js

# Run any command
keyenv run -- python manage.py runserver

# Complex commands (use quotes)
keyenv run -- sh -c "echo $DATABASE_URL && npm test"
```

### How It Works

1. Fetches secrets from the server
2. Injects them as environment variables
3. Runs your command with those variables
4. Secrets are never written to disk

> **Note**
>
> Use `keyenv run` when you want secrets available but don't want a `.env` file on disk.

---

## diff

Show differences between local `.env` file and remote secrets.

```bash
keyenv diff [OPTIONS]
```

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |

### Examples

```bash
keyenv diff

# Comparing .env with development:
#   + NEW_LOCAL_KEY      (local only)
#   - REMOVED_KEY        (remote only)
#   ~ CHANGED_KEY        (modified)
#
# + local only  - remote only  ~ modified
```

### Output

| Symbol | Meaning |
|--------|---------|
| <code>+</code> | Key exists locally but not on server |
| <code>-</code> | Key exists on server but not locally |
| <code>~</code> | Key exists in both but values differ |

### JSON Output

```bash
keyenv diff --json
```

```json
{
  "environment": "development",
  "has_differences": true,
  "differences": [
    { "key": "NEW_LOCAL_KEY", "status": "local_only" },
    { "key": "REMOVED_KEY", "status": "remote_only" },
    { "key": "CHANGED_KEY", "status": "modified" }
  ]
}
```

---

## history

Show version history for a secret.

```bash
keyenv history <KEY> [OPTIONS]
```

### Arguments

| Argument | Description |
|----------|-------------|
| <code>KEY</code> | The secret key to show history for |

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |
| <code>-l, --limit &lt;N&gt;</code> | Number of entries to show (default: 10) |

### Examples

```bash
keyenv history DATABASE_URL

# History for DATABASE_URL (development):
#   v3  2024-01-15 10:30  user@example.com  postgres://prod...
#   v2  2024-01-10 14:22  user@example.com  postgres://staging...
#   v1  2024-01-05 09:00  admin@example.com postgres://dev...
```

### JSON Output

```bash
keyenv history DATABASE_URL --json
```

```json
{
  "key": "DATABASE_URL",
  "environment": "development",
  "history": [
    {
      "version": 3,
      "changed_at": "2024-01-15T10:30:00Z",
      "changed_by": "user@example.com",
      "value_preview": "postgres://prod..."
    }
  ]
}
```

> **Note**
>
> Values are partially masked in the output. Use `keyenv get` to retrieve the full value.