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

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>] [--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>] [--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>]

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 Copilot CLI agent sessions for the current repository. Displays session ID, summary, branch, and last-updated timestamp.

vem sessions [--limit <n>] [--branch <branch>] [--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>

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>]

Backfill commit history and trigger repo indexing. Use --all to include commits across all refs.

vem reindex [--limit <n>] [--all] [--history] [--mode <full|incremental>] [--commit <hash>] [--branch <name>]

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