CLI Installation

The ws command-line tool manages tasks, comments, pages, links, diagrams, milestones, attachments, and test cases directly from the terminal.

Download

Download the ws binary for your platform from the releases page. It's a standalone binary with no dependencies.

Build from Source

Requirements: Go 1.25+

# From the windshift-core repository
cd core/cmd/ws
go build -o ws .

Move the binary to your PATH:

# Linux / macOS
sudo mv ws /usr/local/bin/

# Or add to a local bin directory
mv ws ~/.local/bin/

Verify Installation

ws --help

You should see the available commands and global flags.

Initial Setup

Run ws init in your project directory:

ws init

The CLI uses two configuration tiers and auto-detects which one to run:

  • Global tier (first run on a machine, or --global): opens an OAuth-style browser flow that mints a per-machine bot account and token, then writes ~/.config/ws/config.toml. No copy/paste required.
  • Project tier (inside a project directory, once the global tier is set up): writes ./ws.toml with the workspace key and status aliases.

Common Flags

Flag Description
--global Force global-tier setup (write ~/.config/ws/config.toml)
--manual Skip the browser flow and prompt for a pasted API token
--new-agent Project-tier: provision a dedicated agent + token for this directory
--agent-name Override the generated agent username
-w, --workspace Workspace key to use during project setup

The CLI falls back to --manual automatically when the server has user-managed agents disabled or API-key creation turned off.

Manual Configuration

If you'd rather skip ws init and write the config yourself, use ws config init (see CLI Configuration).

What's Next