Velocity CLI

Manage accounts and workspaces with velocity or vel.

The general CLI manages your Velocity data. velocity-agent separately runs Claude or Codex work. Ordinary management needs no LLM key or subscription.

Install

Use Node.js 20 or newer on Linux, macOS or Windows. Download the archive and checksum from the public 0.2.7 release, verify the SHA-256 checksum, and install the archive. Both aliases use the same package and configuration.

npm install --global ./velocity-quest-cli-0.2.7.tgz
velocity --version
vel --version
vel login --account personal
vel login --account work
vel accounts use work
vel whoami
vel workspaces use my-workspace
vel issues list --json

Accounts and workspace access

Browser sign-in uses PKCE and asks you to select each workspace you authorize. Management sign-in can also authorize account access alone. New memberships do not expand a grant automatically; sign in again to select another workspace. Choose Use a different account on consent to add a different identity.

Use --account NAME and --workspace ID_OR_SLUG for explicit per-command selection. Each profile keeps its own identity, server and workspace default. Scripts with several approved workspaces need a target. --base-url cannot send an existing profile’s credentials to a different server.

vel --account personal --workspace home issues list --json
vel --account work --workspace project issues create --team-id ENGIN --title 'Fix sign-in'
vel login --account staging --base-url https://staging.example.com --no-browser
vel logout --account personal
vel logout --all

SSH sign-in prints a link and reads a hidden paste code. Refresh is automatic and serialized across processes. Logout revokes that profile’s grant; agent sign-ins and other accounts remain separate. OS credential stores are preferred. Headless Linux can use --credential-store file with private files; Windows requires its credential vault.

Commands and scripting

Every current GraphQL operation has a typed command, with account permissions, roles and plan limits enforced by the platform. Use resource and action help for exact flags. Issue identifiers and unambiguous team/status/label names are supported.

Creating or editing cycles and assigning issues to a new cycle requires Pro or higher. Free workspaces retain cycle reads, ordinary edits to existing issues, clearing cycle assignments and cleanup deletion. An upgrade refusal includes a readable message and exits with code 4.

vel issues get ENGIN-123
vel issues update ENGIN-123 --markdown @description.md
vel documents export DOC_UUID --file notes.json
vel documents import DOC_UUID --file notes.json
vel account update-user-preferences --patch '{"theme":"dark"}'
vel notifications watch --after 2026-10-04T00:00:00Z
vel bulk --file operations.json --continue-on-error --json
vel ai smart-create --input '{"text":"Fix the login redirect"}'
vel coverage
vel diagnostics
vel completions bash

--args @file.json and --args - accept JSON files or stdin. JSON results include account and workspace context; sanitized errors use stderr. One-time credential creation requires --show-secrets. Writes are never automatically retried. Ctrl+C cancels requests and polling.

JSON body exports preserve rich text and its version; stale imports fail unless you explicitly use --force. Markdown conversion refuses unsupported formatting unless you allow loss. Supported cursor and offset APIs are fully paged. Version 0.2.0 list commands use typed connections: records are in data.edges[].node, with pageInfo and full filtered totalCount. Legacy array commands use a -legacy suffix. Custom selections include traversal metadata automatically. Use --no-all for one page and --max-pages to bound traversal. New collection pages use first/after, up to 100 records per page, in immutable primary-key order. Edits cannot move rows by changing their display order; inserts, deletes and filter membership remain live rather than a transaction snapshot. Cursors are bound to the account, filters and approved workspace context. Use the corresponding root command to walk a nested collection completely; selecting a nested *Page field fetches just that nested page. Legacy, provider and summary arrays keep explicit limits. REST workspace exports include all matching records in immutable ID order, bounded at 32 MiB; audit downloads refuse more than 5,000 rows with an actionable filtering message. Use JSON format for structured REST output. The server also supports scoped CSV/JSON issue imports with explicit teams and per-row results (100 rows / 1 MiB). CLI 0.2.7 exits 8 for partial or uncertain imports; retry only confirmed failed rows.

Exit codes: 2 input, 3 sign-in, 4 permission or plan, 5 missing, 6 conflict, 7 unavailable or incompatible, 8 partial failure, 130 cancellation. Notification watch polls recorded events and supports timestamp replay with ID deduplication.

Leaving a workspace

vel --workspace ID_OR_SLUG workspaces leave removes your own membership. The last owner must promote another owner or delete the workspace first. Leaving removes your team memberships, workspace API/MCP keys and automation hooks. Any OAuth grant that includes the workspace is revoked in full; sign in again to approve your remaining workspaces. Other account profiles stay separate.

Issue links and subscriptions

vel issues create-issue-relation --source-id ENGIN-1 --target-id ENGIN-2 --type BLOCKS
vel issues remove-issue-relation --source-id ENGIN-2 --target-id ENGIN-1 --type BLOCKED_BY
vel issues subscribe-issue --issue-id ENGIN-1
vel issues get ENGIN-1 --select '{ id identifier relations { id type source { identifier } target { identifier } } subscribers { id displayName } }'
vel issues unsubscribe-issue --issue-id ENGIN-1

Both endpoints must share the selected workspace. Dependencies reject self-links and cycles, including concurrent additions. BLOCKED_BY reverses BLOCKS; RELATES_TO is symmetric.DUPLICATE records that the source duplicates the target, preserving both issues and their statuses. Repeating a link or subscription change creates no extra history or notifications.

Subscriptions add Inbox notifications for later updates and comments, excluding your own actions. Unsubscribing removes your explicit subscription; assignments and mentions retain their own notifications. Status changes and deletion use existing issue lifecycle commands. Issue archive and reusable template operations are currently unavailable.

Social links and public project showcases

Owners and admins can patch only selected Social & Public fields, preserving other workspace settings. A website appears on the public profile and roadmap only while Public Profile is enabled. Project showcases are private by default and use separately reviewed public names and descriptions.

vel --workspace my-workspace workspaces patch-workspace-social-settings --workspace-id WORKSPACE_UUID --settings '{"public_website":"https://example.com"}' --select '{ id settings }'
vel --workspace my-workspace projects set-project-showcase --workspace-id WORKSPACE_UUID --project-id PROJECT_UUID --enabled true --name 'Public project' --description 'Reviewed description' --website https://example.com --github-repositories '["org/repo"]'
vel --workspace my-workspace projects list --workspace-id WORKSPACE_UUID --select '{ edges { node { id name publicShowcase { enabled name description website githubRepositories } } } }'

Websites require full HTTP/HTTPS URLs without credentials; showcases accept up to ten GitHub org/repo paths. Clear optional fields with empty strings or arrays. Unpublishing retains reviewed metadata but removes the public listing. These commands preserve live workspace authorization and roles.

Coverage and browser flows

vel coverage inventories schema commands, REST operations, MCP tools, product pages and linked API gaps. CI rejects stale coverage. Remaining platform APIs include account deletion/full personal-data export/email changes, genuine MFA enrollment and email notification delivery. The matrix records these explicitly.

Use vel open security to inspect security settings (MFA enrollment remains unavailable), vel open integrations --provider github for provider OAuth, or vel open billing for hosted billing. These handoffs open the selected workspace’s settings. AI commands use platform budgets and metering. Agent configuration and recorded runs are available through the CLI; execution uses the agent worker.

In-app notification preferences

vel notifications preferences
vel notifications update-preferences --mention false --issue-assigned false
vel notifications update-preferences --input '{"enabled":false}'
vel notifications reset-preferences

Preferences apply to the selected account across all workspaces. No workspace is required. Partial saves preserve other options, and reset restores all defaults. The server enforces opt-outs when new notifications are created, including issue subscriber delivery; existing Inbox entries remain. Use --account to select another account explicitly. Account-authorized CLI access is required; workspace-connected agents cannot read or change this policy. Email notifications for issue activity and email digests are not available yet. Invitation, account and feedback emails are separate.

Private issue attachments

The published CLI 0.2.7 includes the commands below.

vel attachments upload ENGIN-123 --file ./screenshot.png
vel attachments list ENGIN-123
vel attachments download <attachment-uuid> --output ./download.png
vel attachments remove <attachment-uuid> --issue ENGIN-123
cat capture.bin | vel attachments upload ENGIN-123 --file - --name capture.bin

Files use the normal private platform API with live workspace consent and membership checks. Limits are 4 MiB per file and 50 files per issue. Upload failures include an ID: repeat the same content explicitly with --upload-id to recover without duplication. Mutations are never automatically replayed. Downloads preserve existing output files; --output -writes raw binary stdout and cannot use --json. Inline image removal uses the version-checked issue description mutation, preserving server changes on conflict.

The public package includes a full README, changelog and coverage matrix. Upgrade from a verified release archive;vel diagnostics reports client/server protocol and schema versions.