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:

[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

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:

[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:

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

Use them in commands like filtering tasks by status.