CLI Reference
workspaces-cli (also aliased as ws-cli) from @burdenoff/workspaces-cli. The primary command-line interface for Burdenoff Workspaces platform operations.
Install
npm install -g @burdenoff/workspaces-cli
# or
bun install -g @burdenoff/workspaces-cli
Environment selection
The CLI defaults to production endpoints. Select a different environment via BURDENOFF_ENV:
| Variable | Values | Default | Description |
|---|---|---|---|
BURDENOFF_ENV | local | alpha | prod | prod | Selects the default GraphQL gateway endpoints and OIDC issuer. |
Examples:
# Production (default)
ws-cli auth login
# Alpha
BURDENOFF_ENV=alpha ws-cli auth login
# Local dev
BURDENOFF_ENV=local ws-cli auth login
When BURDENOFF_ENV is unset or invalid, the CLI defaults to prod.
Default endpoints by environment
| Environment | Workspace gateway | Global gateway |
|---|---|---|
prod (default) | https://graphqlworkspaces.burdenoff.com/workspaces/graphql | https://graphql.burdenoff.com/global/graphql |
alpha | https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql | https://alphagraphql.burdenoff.com/global/graphql |
local | http://localhost:4003/workspaces/graphql | http://localhost:4000/global/graphql |
Override individual endpoints permanently:
ws-cli config set workspaceEndpoint https://custom.example/workspaces/graphql
ws-cli config set globalEndpoint https://custom.example/global/graphql
ws-cli config set oidcIssuer https://custom.auth.example
Top-level command groups
| Group | What |
|---|---|
auth | Authentication (login, logout, status, token, refresh) |
workspace | Workspace context (list, current, set) |
project | Project management (list, create, update, archive, delete) |
conversation | Conversations (channels, messages, threads) |
file | Files (upload, download, list, delete) |
tag | Tags (create, list, assign, remove) |
group | Groups and teams (list, create, update, delete) |
rbac | RBAC operations (check, list roles, list permissions) |
scheduler | Scheduler jobs (create, list, cancel, monitor) |
webhook | Webhooks (create, list, update, delete, deliveries) |
billing | Billing (plans, invoices, usage) |
config | CLI local settings |
Common examples
# Auth
ws-cli auth login
ws-cli auth status
ws-cli auth token --workspace
# Workspace
ws-cli workspace list
ws-cli workspace set <id>
# Projects
ws-cli project list --workspace <id>
ws-cli project create --name "Q3 Roadmap" --workspace <id>
ws-cli project update <id> --name "Q3 Roadmap v2"
# Conversations
ws-cli conversation channels list
ws-cli conversation send --channel <id> --body "Hello team"
# Files
ws-cli file upload ./report.pdf --project <id>
ws-cli file list --project <id>
# Tags
ws-cli tag create --name urgent --color #ff0000
ws-cli tag assign <tagId> --resource <id> --type PROJECT
# RBAC
ws-cli rbac check --user <id> --action read --resource PROJECT:<id>
# Scheduler
ws-cli scheduler create --name "Daily backup" --cron "0 2 * * *" --jobType backup
# Webhooks
ws-cli webhook create --name slack --url https://hooks.slack.com/... --events "file.uploaded,project.created"
Each command's full flag list is in ws-cli <group> <subcommand> --help.
Development
git clone https://github.com/algoshred/workspaces-cli.git
cd workspaces-cli
bun install
bun run dev # Run in development mode
bun run build # Production build
bun run test # Run tests
bun run sanity # All checks (format, lint, type-check, test, build)
Source
- Repository:
github.com/algoshred/workspaces-cli - Package:
@burdenoff/workspaces-clion npm