# CLI Configuration

The `ws` CLI uses a layered configuration system. Settings can come from config files, environment variables, or CLI flags.

## Priority Order

Settings are resolved in this order (highest priority first):

1. **CLI flags** - `--url`, `--token`, `--workspace`, `--output`
2. **Environment variables** - Prefixed with `WS_`
3. **Project config** - `./ws.toml` in the current directory
4. **Global config** - `~/.config/ws/config.toml`

## Config File Format

Both project and global configs use the same TOML format:

```toml
[server]
url = "https://windshift.example.com"
token = "your-api-token"

[defaults]
workspace_key = "PROJ"

[cache]
user_id = "abc123"

[status_aliases]
done = "To Review"
wip = "In Progress"
todo = "Open"
```

### Sections

| Section | Description |
|---------|-------------|
| `[server]` | Server URL and API token |
| `[defaults]` | Default workspace key |
| `[cache]` | Cached values (user ID) |
| `[status_aliases]` | Shortcuts for status names |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `WS_URL` | Windshift server URL |
| `WS_TOKEN` | API token |
| `WS_WORKSPACE` | Default workspace key |

## Global Flags

These flags are available on all commands:

| Flag | Description |
|------|-------------|
| `--config` | Path to a specific config file |
| `--url` | Windshift server URL |
| `--token` | API token |
| `--workspace` | Workspace key |
| `--output` | Output format: `json` or `table` (default: `table`) |

## Creating a Config

### Interactive Setup

```bash
ws config init
```

Prompts for server URL, token, default workspace, and status aliases. Saves to `./ws.toml` by default. Use `--global` for `~/.config/ws/config.toml`.

### Manual Setup

Create `ws.toml` in your project root:

```toml
[server]
url = "https://windshift.example.com"
token = "wst_abc123..."

[defaults]
workspace_key = "ENG"
```

## Status Aliases

Aliases let you reference statuses by short names instead of full status names:

```toml
[status_aliases]
done = "To Review"
wip = "In Progress"
blocked = "Blocked"
```

Use them in commands like filtering tasks by status.