CLI Commands

The ws CLI manages tasks, comments, pages, links, diagrams, milestones, attachments, test cases, assets, time, labels, agent skills, 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 search`	Full-text search across accessible work items
`ws task`	Create, edit, list, search, 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 label`	List item labels and attach them to work items
`ws page`	Manage and search 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 asset`	Manage assets; `ws asset-set` and `ws asset-type` inspect their containers
`ws time`	Time projects, worklogs, and the timer
`ws skill`	Inspect the workspace agent skill library
`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

Search

Full-text search across every work item you can access:

ws search "login bug"
ws search "rate limit" --limit 5

--limit caps results (server default if omitted, max 100). To search within a single workspace, use ws task search below.

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 (name or ID)
`--status`	Status ID
`--priority`	Priority ID
`--assignee`	Assignee user ID
`--parent`	Parent item ID
`--iteration`	Iteration (name or numeric ID)
`--project`	Project ID (numeric)
`--due-date` / `--start-date` / `--end-date`	Dates in `YYYY-MM-DD`
`--custom-field`	Custom field value as `<field>=<value>` (repeatable; field is a name or ID)
`--web`	Open the new item in a browser

ws task edit accepts the same --due-date, --start-date, --end-date, --custom-field, --iteration, and --project flags, plus --type-status to target the new workflow's status when changing type.

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.

Search Tasks

ws task search "login bug"          # Full-text search within the workspace
ws task search login --limit 5

Children, Parent, History

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
ws task parent CP-42                # Parent of an item
ws task history CP-42 --limit 25    # Change history

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 search runbook                       # Title search within the workspace
ws page search "incident response" --limit 5
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

Label Commands

Work-item labels (separate from page labels). Names or IDs are accepted, and --set is exclusive with --add/--remove.

ws label ls                                 # Workspace item-label catalog
ws task label PROJ-12 --add backend         # Attach by name (or ID)
ws task label PROJ-12 --add backend,urgent --remove frontend
ws task label PROJ-12 --set backend,urgent  # Atomic replace

Asset Commands

Manage assets and inspect their sets and types. Deleting an asset is not exposed in the CLI; it is API-only and opt-in.

ws asset ls                                  # Assets in the default/visible set
ws asset ls --set 3 --type 7 --status 2      # Filter by set, type, status
ws asset ls -q "LAP-001" --limit 50 --page 1 # Free-text title search, paged
ws asset get 42
ws asset create -t "MacBook Pro" --type 7 --tag LAP-001 --category 2 --status 1
ws asset edit 42 -t "New title" --status 3
ws asset import assets.csv --set 3 --type 7  # Bulk CSV import (one type per run)

ws asset-set ls                              # Read-only: asset sets
ws asset-set get 3
ws asset-type ls --set 3                     # Read-only: asset types
ws asset-type get 7

ws asset create requires --title and --type. ws asset import requires --type and creates every CSV row as that type; --status and --category set defaults for all rows.

Time Commands

ws time project ls                           # Time projects you can log against

ws time worklog ls --date-from 2026-06-01 --date-to 2026-06-30 --project-id 4
ws time worklog add --project-id 4 --duration 1h30m --date 2026-06-17 \
  --description "Pairing" --item-key PROJ-12
ws time worklog edit 88 --duration 2h
ws time worklog rm 88

ws time timer start --project-id 4 --item-id 123 --description "Investigating"
ws time timer status                         # Current running timer
ws time timer stop                           # Stop and log it

Only one timer runs at a time. --duration accepts natural forms like 2h, 30m, 2h30m; --duration-minutes takes a raw integer.

Skill Commands

Read-only view of the workspace agent skill library (the knowledge packs attached to coding agents).

ws skill ls                                  # Index of enabled agent skills
ws skill get 5                               # Full markdown body of a skill

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