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

CLI flags - --url, --token, --workspace, --output, --config
Environment variables - Prefixed with WS_
Project config - Nearest ws.toml walking up from the current directory
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 or numeric IDs

Environment Variables

Variable	Description
`WS_URL`	Windshift server URL
`WS_TOKEN`	API token
`WS_WORKSPACE`	Default workspace key
`WS_DEBUG_HTTP`	Set to `1` to log one-line HTTP request/response info to stderr

Global Flags

These flags are available on every command:

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

Creating a Config

Recommended: `ws init`

ws init

Runs an OAuth-style browser flow to mint a token on first use, then sets up ./ws.toml for the current project. See CLI Installation for details and flags.

Manual: `ws config init`

ws config init                # Create ./ws.toml
ws config init --global       # Create ~/.config/ws/config.toml
ws config init --non-interactive

Useful when you need to script the setup or paste a token rather than completing the browser flow.

Hand-Written

Create ws.toml in your project root:

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

[defaults]
workspace_key = "ENG"

Inspecting the Effective Config

ws config show

Prints the merged configuration from all sources (flags, env, project, global).

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 anywhere a status is accepted, for example:

ws task move PROJ-45 done
ws task ls -s ~done           # Negation: exclude done

Refreshing Aliases

If statuses are renamed on the server, or your aliases still hold stale names instead of numeric IDs, refresh them:

ws config refresh

This re-fetches workspace statuses and rewrites the aliases section with numeric IDs (stable across renames).