CLI Configuration

The ws CLI uses layered configuration. Settings come from configuration files, environment variables, or CLI flags.

Priority Order

The CLI resolves settings in this order, from highest priority to lowest:

CLI flags: --url, --token, --workspace, --output, and --config.
Environment variables: Values prefixed with WS_.
Project configuration: The nearest ws.toml found from the current directory upward.
Global configuration: ~/.config/ws/config.toml.

Config File Format

Project and global configuration files 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

On first use, this command opens an OAuth-style browser flow to mint a token. It 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

Use this command to script setup or paste a token instead of completing the browser flow.

Hand-Written

Create ws.toml in your project root:

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

[defaults]
workspace_key = "ENG"

Inspecting the Effective Config

ws config show

Prints the configuration that the CLI merges from flags, environment variables, project files, and global files.

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 command fetches workspace statuses again. It rewrites the aliases section with numeric IDs, which stay stable across renames.