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 is 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 selects the right one:

  • Global tier: On the first run on a machine, or with --global, it opens an OAuth-style browser flow. It then creates a per-machine bot account and token and writes ~/.config/ws/config.toml.
  • Project tier: In a project directory, after global setup, it writes ./ws.toml with the workspace key and status aliases.

Common Flags

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

The CLI uses --manual automatically when the server disables user-managed agents or API-key creation.

Manual Configuration

To skip ws init and write the configuration yourself, use ws config init. See CLI Configuration.

What's Next