CLI / Install and usage guide

Install and usage guide

Everything you need to get the ws CLI running, authenticated, and useful. The simplest install is a single npm command that works on every platform. A shell script, a PowerShell one-liner, and manual binaries are also available if you prefer to manage the install yourself.

Install

npm (any platform)

The simplest option. Works on macOS, Linux, and Windows wherever you have Node.js installed, and keeps the CLI on your PATH automatically.

Terminal

npm install -g @workspark/cli

macOS and Linux (shell script)

Run this in your terminal. The script detects your OS and architecture, downloads the correct binary, and places it in /usr/local/bin.

Terminal

curl -fsSL https://workspark.io/cli/install.sh | sh

Windows (PowerShell)

PowerShell

irm https://workspark.io/cli/install.ps1 | iex

Verify the install

Terminal

ws --version

Manual download

Download the archive for your platform, extract the binary, and place it somewhere on your PATH.

Platform	File
macOS (Apple Silicon)	ws-darwin-arm64.tar.gz
Linux (x86_64)	ws-linux-amd64.tar.gz
Linux (arm64)	ws-linux-arm64.tar.gz
Windows (x86_64)	ws-windows-amd64.zip
Windows (arm64)	ws-windows-arm64.zip

macOS / Linux manual install steps

Terminal (adjust filename for your platform)

curl -fLO https://downloads.workspark.io/ws-cli/ws-darwin-arm64.tar.gz
tar -xzf ws-darwin-arm64.tar.gz
sudo mv ws /usr/local/bin/ws
chmod +x /usr/local/bin/ws

No-sudo alternative: install to your home directory

If you prefer not to use sudo, install to ~/.local/bin instead and add it to your PATH.

Terminal

mkdir -p ~/.local/bin
mv ws ~/.local/bin/ws
chmod +x ~/.local/bin/ws

Add the following line to your ~/.zshrc or ~/.bashrc:

~/.zshrc or ~/.bashrc

export PATH="$HOME/.local/bin:$PATH"

Then restart your shell or run source ~/.zshrc. Verify with ws --version and ws --help.

Authenticate

ws auth login

Opens the browser to sign in.

ws auth whoami

Shows your account details and org memberships, including the active org and your roles.

ws auth status

Shows current authentication status.

ws auth logout

Clears the stored session.

Configure your organisation

Most commands operate against a single active organisation. Set it once and all subsequent commands use it automatically. You can always override with the --organization flag.

ws config init

First-time setup wizard. Walks you through selecting your organisation.

ws organizations list

Lists all organisations you belong to.

ws organizations use

Interactive picker to set your active organisation. Or pass an org ID directly: ws organizations use 01KN17QXK5V42A1W8A4FSDF2KX.

Everyday commands

A selection of common commands to get you oriented. Every command accepts --help for a full list of flags.

Accomplishments

ws accomplishments create \
  --content "Shipped the new onboarding flow, cutting time-to-first-value by 40%." \
  --entry-date 2026-05-28

Logs a new accomplishment. AI enrichment fills in the title and category automatically if you omit them. Valid categories: create, execute, lead, learn, maintain, plan, research, share, support. Defaults to your own member record when --member-id is omitted.

ws accomplishments list

Lists your recent accomplishments.

ws accomplishments list \
  --filter entry_date_from=2026-01-01 \
  --filter entry_date_to=2026-03-31

Filter by date range. Useful for preparing a self-review.

ws accomplishments get 01KN17QXK5V42A1W8A4FSDF2KX

Fetch a single accomplishment by ID.

Members

ws members list

Lists members in the active organisation.

ws members list --match "Alice"

Search members by name.

OKRs

ws okrs cycles list --match "2026 H1"

Find an OKR cycle by name.

ws okrs list 01KN17QXK5V42A1W8A4FSDF2KX

List OKRs in a cycle (pass the cycle ID).

Tasks

ws tasks boards list

List task boards in the active organisation.

Tips

Run ws <command> --help for any subcommand to see all available flags.
Add --output json to any list or get command for machine-readable output, useful for scripting or piping into jq.
Run ws auth whoami before any write command to confirm you are operating against the right organisation.

Keeping up to date

Check your current version with ws --version. The CLI checks compatibility with the server on each run and prints an update notice when a newer version is recommended or required. To upgrade, re-run the install method you used. For npm:

Terminal

npm update -g @workspark/cli

Or re-run the shell script (macOS / Linux):

Terminal

curl -fsSL https://workspark.io/cli/install.sh | sh

Back to CLI overview Use with AI agents