Vectal CLI

Manage your Vectal tasks, projects, notes and habits from the terminal. Built for humans and AI agents (Claude Code, Codex, Cursor, ...).

Install

npm install -g vectal
# or zero-install:
npx vectal --help

Auth

Get an API key in the Vectal app under Settings > API Keys, then:

vectal login            # prompts for the key, verifies it, saves to ~/.config/vectal/config.json
# or for agents / CI:
export VECTAL_API_KEY=vec-...

Usage

vectal whoami
vectal task list --status active
vectal task add "Review PR #42" --importance 80 --due 2026-07-10
vectal task done <task-id>
vectal project list
vectal note add "Meeting notes" --content "## Agenda..."
vectal habit list
vectal habit check <habit-id>
vectal search "onboarding"

Every command supports --help. Run vectal --help for the full command tree.

For AI agents

• Add --json to any command to get the raw API response (stable envelope: {"data": ...}).
• Exit code 0 = success, 1 = error. Errors go to stderr as Error (code): message.
• Checklist items live as markdown checkboxes (- [ ] item) inside a task's context field — read them with vectal task get <id> and update them with vectal task update <id> --context "...".
• Point the CLI at another backend with VECTAL_API_URL (e.g. http://localhost:8000 for local dev).

Development

cd cli
npm install
npm run build     # compiles src/ -> dist/
node dist/index.js --help