CLI Reference

Initialize local .vem/ artifacts, add .vem/ to .gitignore, and optionally install a git pre-push auto-sync hook.

vem init

Authenticate with an API key or browser-based login.

vem login [api-key]

Clear your local API key and sign out of the CLI.

vem logout

Link the current repo to a project (select or create when no ID is provided).

vem link [project-id]

Open the web app to the linked (or specified) project.

vem project open [project-id]

Unlink the current repo from its vem project. Asks for confirmation.

vem unlink

Push local .vem state to the cloud as a snapshot (with git_hash + snapshot_hash provenance). New snapshots start pending until webhook verification.

vem push [--dry-run] [--force]

Pull the latest snapshot from the cloud to your local .vem directory.

vem pull

Search project memory for tasks and context.

vem search "query"

Ask a question against project memory (commits, diffs, tasks, and code).

vem ask "question" [--path <path>] [--thread-id <id>]

Launch AI tools wrapped with automatic context injection, task tracking, and strict memory enforcement. This is the most powerful way to use VEM.

vem agent [tool] [--task <id>]

Interactive wizard that guides you through setting up powerful workflows from scratch.

vem quickstart

View your power feature usage score and see which workflows you're using. Track your progress toward mastery.

vem status

Start a paired runner that powers the web Workspace terminal and claims queued local-runner jobs for the linked project checkout. Multiple runner processes can work in parallel.

vem runner [--agent <command>] [--poll-interval <seconds>] [--once]

Apply vem_update blocks from agent output to your local memory artifacts. Auto-detected after agent sessions.

vem finalize [--file <path>]

List project tasks from VEM Cloud (with local fallback when offline).

vem task list [--all] [--status <status>] [--done] [--deleted]

Show deep metadata for a specific task, including history and context.

vem task details --id <id>

View a parent task and all of its nested subtasks.

vem task subtasks --parent <id>

Manage the long-form context associated with a task.

vem task context <id> [--set <text>|--append <text>|--clear]

Assign a task to a user (prompts for assignee when omitted).

vem task assign <id> [assignee]

Create a new task with metadata, dependencies, and validation steps.

vem task add <title> [--priority <p>] [--description <d>] [--tags <tags>] [--type <t>] [--estimate-hours <hours>] [--depends-on <ids>] [--blocked-by <ids>] [--recurrence <rule>] [--owner <id>] [--reviewer <id>] [--parent <id>] [--order <n>] [--due-at <iso>] [--validation <steps>] [--cycle <id>] [--impact-score <score>] [--actor <name>] [--reasoning <r>]

Update task metadata (tags, dependencies, estimates, due dates).

vem task update <id> [--tags <tags>] [--type <t>] [--estimate-hours <hours>] [--depends-on <ids>] [--blocked-by <ids>] [--recurrence <rule>] [--owner <id>] [--reviewer <id>] [--parent <id>] [--order <n>] [--due-at <iso>] [--validation <steps>] [--cycle <id>] [--impact-score <score>] [--actor <name>] [--reasoning <r>]

Start working on a task (set status to in-progress). Interactive selection when no ID provided.

vem task start [id] [--reasoning <r>] [--actor <name>]

Mark a task as complete with evidence, reasoning, and validation.

vem task done [id] [--evidence <e>] [--reasoning <r>] [--validation <v>] [--context-summary <summary>] [--actor <name>]

Mark a task as blocked with a required reason.

vem task block <id> --reasoning <r> [--blocked-by <ids>] [--actor <name>]

Unblock a task (set status back to todo).

vem task unblock <id> [--reasoning <r>] [--actor <name>]

Soft delete a task while keeping it in history.

vem task delete <id> [--reasoning <r>]

View agent sessions linked to a specific task.

vem task sessions <id>

Analyze the flow state and history of a task.

vem task flow [id]

View the impact score (RICE-based priority) for a task.

vem task score [id]

Mark a task as ready (all blockers resolved, waiting to be picked up).

vem task ready [id]

Create a follow-up iteration of a completed task.

vem task iterate <id>

Launch an AI agent (Claude, Gemini, etc.) with automatic context injection from your current task.

vem agent [command] [--task <id>]

Generate a raw vem_pack block (JSON or Markdown) for manual injection into prompts.

vem pack [--json]

Apply a vem_update block from an agent response to your local memory.

vem finalize [--file <path>]

Show project context and current state from cloud when available, with local cache fallback.

vem context show

Persist project context and/or current state. Writes to cloud when linked, and always updates local cache.

vem context set [--context "<text>"] [--current-state "<text>"]

Record an architectural decision (ADR) with optional task linking.

vem decision add "<title>" --context "<why>" --decision "<what>" [--tasks TASK-001,TASK-002]

List recent agent sessions (Copilot, Claude, Gemini, Cursor, Windsurf, Codex) for the current repository. Displays source, session ID, summary, branch, and last-updated timestamp.

vem sessions list [--limit <n>] [--branch <branch>] [--source <sources>] [--all]

Interactively import a session into vem project memory. Prompts to add a changelog entry from the session summary and link the session as evidence on an active task. Accepts full UUIDs or short prefixes.

vem sessions import <id>

List all goal cycles for the linked project.

vem cycle list

Create a new goal cycle with an optional name.

vem cycle create [name]

Mark a cycle as the active in-progress cycle.

vem cycle start <id>

Close a cycle and move it to completed state.

vem cycle close <id>

Set focus on a specific cycle (or the active one) to filter task views.

vem cycle focus [id]

Run full validation for a cycle: pre-flight checks + AI review. Options: --skip-sensors, --skip-ai, --backend <cloud|local>, --strict.

vem cycle validate <id>

Show a health snapshot for a cycle, including sensor metrics, task completion rate, and risk indicators.

vem cycle health [id]

Generate a retrospective report for a completed cycle, summarising velocity, blockers, and lessons learned.

vem cycle retrospective <id>

Pull the latest instruction files from the cloud into the local repo.

vem instructions pull

Push local instruction files to the cloud for versioning.

vem instructions push

Check whether local instruction files are in sync with the cloud.

vem instructions status

List the version history of instruction files stored in the cloud.

vem instructions versions

Revert instruction files to a specific version by version ID.

vem instructions revert <versionId>

Manage the offline snapshot queue.

vem queue [--list] [--retry] [--clear]

Archive older memory entries to keep context small.

vem archive [--all] [--decisions] [--changelog] [--tasks] [--older-than <days>] [--keep <count>]

Show differences between local .vem/ state and the last pushed snapshot.

vem diff [--detailed] [--json]

Run comprehensive health checks on your VEM setup (auth, project, git, data integrity).

vem doctor [--json]

Analyze current git changes and suggest memory updates for changelog, decisions, context, and current state.

vem summarize [--staged]

Check login status, linked project, and local task counts.

vem status