CLI Commands

The ws CLI manages tasks, comments, pages, links, diagrams, milestones, attachments, test cases, and workspaces.

Run ws --help to see the full command tree, or ws <command> --help for any subcommand.

Top-Level Commands

Command	Purpose
`ws init`	Set up the CLI (browser auth) and a project (workspace + `ws.toml`)
`ws task`	Create, edit, list, and move work items
`ws comment`	View, add, edit, and delete comments on items
`ws link`	Link items to other items, pages, and test cases
`ws page`	Manage workspace knowledge pages (wiki)
`ws page-label`	Manage page labels
`ws diagram`	Create and manage Excalidraw / mermaid diagrams on items
`ws milestone`	Manage milestones
`ws attachment`	List and download work-item attachments
`ws test`	Manage test cases, sets, runs, and results
`ws workspace`	List and inspect workspaces
`ws status`	List workspace statuses
`ws item-type`	List workspace item types
`ws priority`	List workspace priorities
`ws config`	Configuration commands (`init`, `show`, `refresh`, `docs`)
`ws version`	Print version information
`ws completion`	Generate shell completion scripts

Task Commands

List Tasks

ws task ls                  # All accessible tasks
ws task ls -s ~done         # Exclude done (negation with ~)
ws task ls --created today  # Created today
ws task ls --updated -7d    # Updated in last 7 days
ws task mine                # Assigned to me
ws task created             # Created by me

Flag	Description
`-s, --status`	Filter by status (use `~status` to exclude)
`--assignee`	Filter by assignee ID
`--priority`	Filter by priority ID
`--type`	Filter by item type ID
`--created`	Filter by creation date (`today`, `week`, `month`, `year`, or `-Nd`)
`--updated`	Filter by update date (same values as `--created`)

Get Task Details

ws task get PROJ-45         # By workspace key
ws task get 123             # By numeric ID
ws task get PROJ-45 --web   # Open in browser

Returns task fields, available status transitions, and the 10 most recent comments.

Create a Task

ws task create -t "Fix login bug"
ws task create -t "New feature" -d "Detailed description" --type 1 --priority 2
ws task create -t "Bug" --web         # Open in browser after creation

Flag	Description
`-t, --title`	Title (required)
`-d, --description`	Description (Markdown; supports `\n`, `\t`, `\\`)
`--type`	Item type ID
`--status`	Status ID
`--priority`	Priority ID
`--assignee`	Assignee user ID
`--parent`	Parent item ID
`--web`	Open the new item in a browser

Edit a Task

ws task edit CP-30 -t "New title"
ws task edit CP-30 --priority 2 --assignee 3
ws task edit CP-30 --type 1 --type-status 5   # Change type, target the new workflow's status

Move (Change Status)

ws task move PROJ-45 done           # Status alias
ws task move PROJ-45 "In Progress"  # Exact name (case-insensitive)
ws task move PROJ-45 prog           # Partial match
ws task move PROJ-45 3              # Status ID

Workflow transitions are validated server-side.

Children of an Epic / Item

ws task children CP-11              # Stories under epic CP-11
ws task children CP-11 -s ~done     # Exclude done
ws task children CP-11 --type 3     # Only one item type

Assign to a Milestone

ws task set-milestone PROJ-123 5            # By milestone ID
ws task set-milestone PROJ-123 "v1.0"       # By milestone name (fuzzy)
ws task set-milestone PROJ-123 --clear      # Remove from milestone

Comment Commands

ws comment list PROJ-45
ws comment add PROJ-45 -m "## Status\n\n- Fixed bug\n- Added tests"
ws comment edit 123 -m "Updated content"
ws comment delete 123

-m content is Markdown and supports \n, \t, \\ escapes.

Link Commands

Links connect items to items, items to pages, or items to test cases. The link type is auto-selected when only one is compatible.

ws link add WI-1 page:42                       # auto: Page
ws link add WI-1 test:5                        # auto: Tests
ws link add WI-1 WI-2                          # auto: Relates To
ws link add WI-1 WI-2 --type Implements        # explicit type
ws link ls WI-1
ws link ls page:42
ws link rm 123
ws link types                                  # show available link types

Entity references:

Prefix	Meaning
`WI-1`	Work item by workspace key
`item:42`	Work item by numeric ID
`page:42`	Page by numeric ID
`test:5`	Test case by numeric ID (alias `test_case:5`)

Page Commands

Pages are workspace knowledge (wiki) pages.

ws page list                                # All pages in workspace
ws page list --label design,spec            # Filter by labels (AND)
ws page get 42 > onboarding.md              # Markdown source to stdout
ws page get 42 -o json
ws page create --file onboarding.md
ws page create --title "Runbook" -f runbook.md --upload-assets
ws page edit 42 --file rewritten.md
ws page edit 42 --title "New title" --file rewritten.md
ws page move 42 --parent 7 --after 11
ws page move 42 --root
ws page archive 42
ws page history 42 --limit 25
ws page restore 42 99                       # Restore page 42 from revision 99

--upload-assets scans markdown for ![alt](./local.png) references, uploads each as a page attachment, and rewrites the markdown before posting.

Labels on a Page

ws page labels 42                           # Show current labels
ws page labels 42 --add 5,7 --remove 11
ws page labels 42 --set 5,7,9               # Atomic replace

Page Permissions

ws page permissions 42
ws page grant 42 --principal 7 --type user --level edit
ws page revoke 42 <permission-id>
ws page inheritance 42 --off
ws page inheritance 42 --on

Page Labels

Workspace-scoped labels that attach only to pages (separate from work-item labels).

ws page-label list
ws page-label create --name design --color "#3B82F6"
ws page-label edit 5 --name "Design docs"
ws page-label delete 5

Diagram Commands

Diagrams are stored as Excalidraw scene JSON. Mermaid sources are stored as a seed wrapper and rendered the first time the diagram opens in the editor.

ws diagram create PROJ-45 --name "Auth flow" --mermaid "graph TD; A-->B"
ws diagram create PROJ-45 --name scene --from-file scene.json
cat scene.json | ws diagram create PROJ-45 --name scene --from-file -
ws diagram list PROJ-45
ws diagram get 12
ws diagram update 12 --name "Renamed"
ws diagram delete 12

Provide content via exactly one of --mermaid, --excalidraw, or --from-file.

Milestone Commands

ws milestone ls                             # Workspace milestones
ws milestone ls --status in-progress
ws milestone ls --global                    # Global milestones (requires access)
ws milestone get 5 --progress
ws milestone create -n "v2.0 Release" --target 2024-06-01
ws milestone update 5 --status completed

Status values: planning, in-progress, completed, canceled.

Attachment Commands

Listing and downloading only. Upload is web-only.

ws attachment list PROJ-45
ws attachment download 42                      # ./<original-filename>
ws attachment download 42 --to /tmp/spec.pdf   # exact path
ws attachment download 42 --to /tmp/           # directory + original filename
ws attachment download 42 --to - > out.bin     # stream to stdout

Test Commands

Test Cases

ws test case ls
ws test case ls --folder 5
ws test case get 42                         # Includes ordered step sequence

Test Sets

ws test set ls
ws test set get 3

Test Runs

ws test run ls
ws test run ls --set 3
ws test run mine
ws test run get 7
ws test run start 3 --name "Sprint 12 regression"
ws test run start --template 5
ws test run end 7

Record a Result

ws test result 7 1 passed
ws test result 7 2 failed --notes "Button not visible on mobile"

Status values: passed, failed, blocked, skipped.

Workspace, Status, Priority, Item Types

ws workspace ls
ws workspace info                # Default workspace
ws workspace info PROJ           # By key

ws status ls                     # All statuses (or filtered by -w)
ws priority ls
ws item-type ls

ws workspace info includes statuses, item types, and workflow transitions.

Config Commands

ws config init                   # Create ./ws.toml (project config)
ws config init --global          # Create ~/.config/ws/config.toml
ws config show                   # Print effective config (merged sources)
ws config refresh                # Re-fetch statuses, regenerate aliases with numeric IDs
ws config docs                   # Rewrite WINDSHIFT.md from live workspace (no ws.toml/AGENTS.md changes)

Use ws init instead of ws config init for the full setup (auth via browser + project workspace).

Output Formats

Every command accepts -o / --output:

Value	Notes
`json`	Default. Machine-readable, pipe-friendly.
`table`	Human-readable columns.
`csv`	Spreadsheet-friendly.

ws task mine                                # JSON by default
ws task mine -o table                       # Pretty table
ws task mine -o json | jq '.[].key'
ws task mine -o csv > my-tasks.csv

Shell Completions

source <(ws completion bash)
ws completion zsh > "${fpath[1]}/_ws"
ws completion fish > ~/.config/fish/completions/ws.fish
ws completion powershell | Out-String | Invoke-Expression