mindvm CLI

The mindvm CLI lives in mindvm-cli. It’s the primary authoring surface for MindVM agents: a local mindvm/ folder is the source of truth, and the CLI’s init / dev / deploy verbs sync it to the platform. The same binary also wraps the /api/sdk/* runtime surface for ops, scripting, and CI gates.

A second binary, mindvm-tui, is the interactive terminal UI for chatting with a configured agent.

Install

Pre-built binaries: see the Releases page.

From source:

git clone https://github.com/tavora-ai/mindvm-cli
cd mindvm-cli
go install ./cmd/mindvm      # CLI
go install ./cmd/mindvm-tui  # TUI

Configure

Two paths, both work:

Interactive (recommended)

mindvm login

Prompts for the MindVM URL and a project-scoped API key, validates the key against /api/sdk/project, and writes the config to ~/.mindvm.yaml. Subsequent commands pick it up automatically.

Environment variables

export MINDVM_URL=https://api.mindvm.ai
export MINDVM_API_KEY=tvr_...

mindvm show

Flags

mindvm --url https://api.mindvm.ai --api-key tvr_... show

Precedence is flag > env > config file. The CLI never echoes the key back at you — mindvm show confirms the connection by showing the project metadata.

API keys are project-scoped (one key, one project). To work against multiple projects from one shell, swap MINDVM_API_KEY per command or pass --api-key directly.

Global flags

Flag	Effect
--api-key <key>	API key (tvr_…); env: MINDVM_API_KEY.
--url <url>	Server URL; env: MINDVM_URL.
--config <path>	Override ~/.mindvm.yaml.
--output text|json	json is structured and pipeable into jq. Default text.
--quiet / -q	Suppress status messages — emit data only. Pairs well with --output json.

Subcommand reference

Every subcommand prints --help; the tables below are the orienting map.

Code-first authoring

The authoring loop:

mindvm init                       # scaffold mindvm/{mindvm.jsonc, agents/...}
mindvm dev                        # watch + sync drafts on save (250ms debounce)
mindvm run <agent> "<input>"      # run the local draft; writes .runs/<ts>-<agent>-<sid>.md
mindvm deploy                     # validate + sync + snapshot as an immutable version
mindvm deploy --dry-run           # validate only — CI gate

Agent identity is (project, local_id) from mindvm.jsonc and agent.jsonc. Renames and deletes are explicit:

mindvm rename <old-id> <new-id>   # keeps the server-side binding stable
mindvm delete <id> [--yes]        # destroys the agent + cascades versions, sessions, evals

Resolved-config inspection:

mindvm config show <agent>        # resolved JSON (post env-var substitution)
mindvm open <ref>                 # open the source file backing a config field

Session forensics

Every mindvm run writes a self-contained markdown trace to mindvm/.runs/. Browse them offline:

mindvm session latest             # newest run for any agent in the project
mindvm session get <id-prefix>    # full markdown for a specific session
mindvm session list               # most-recent N sessions in the project

Retention defaults to 50 runs (override via mindvm.jsonc → retention.runs). For server-side traces — including SDK-triggered and scheduled runs — use the session detail view in the browser (/sessions/:id).

Agents — runtime

The runtime side of agents (sessions, not configs):

mindvm agents list                                  # all sessions in this project
mindvm agents create [--system "..."] [--title]     # new ad-hoc session
mindvm agents get      <session-id>
mindvm agents run      <session-id> "<message>"     # stream a turn
mindvm agents interactive <session-id>              # one-off REPL — TUI is the richer surface
mindvm agents delete   <session-id>
mindvm agents prompt                                # print the runtime system prompt for this project

Skills

Skills are authored as .js / .md files under mindvm/agents/<id>/skills/ and arrive via mindvm dev. The CLI’s skills verbs are read-only:

mindvm skills list
mindvm skills get <skill-id>
mindvm skills authoring-guide -o skill-authoring.md   # → feed to your editor's LLM

mindvm skills authoring-guide fetches the live runtime’s authoring reference — sandbox primitives, reserved names, ES5.1 constraints — and writes Markdown you can hand to Claude Code / Cursor as context when drafting skills.

MCP servers

MCP servers are declared inline in agent.jsonc → mcp and flow through mindvm dev. There is no mindvm mcp subcommand — edit agent.jsonc, save, and mindvm dev syncs and validates the block (URL reachable, auth refs resolve). See MCP servers for the JSONC shape.

Documents & search

mindvm stores list
mindvm stores create --name "Support docs" --description "..."
mindvm stores delete <store-id>

mindvm documents upload  --store <store-id> ./faq.md
mindvm documents upload  --store <store-id> ./docs/              # whole directory
mindvm documents wait    <doc-id>          # block until embeddings ready
mindvm documents list    --store <store-id>
mindvm documents get     <doc-id>
mindvm documents delete  <doc-id>

mindvm search "what document formats are supported?" --store <store-id> --limit 5

Naming drift

The CLI’s stores subcommand wraps the same surface the SDK exposes as Index / createIndex. The rename to indexes is rolling through the codebase; the CLI subcommand will become mindvm indexes in a future release. Use mindvm stores until then.

Evals (advisory)

Eval cases live as JSON files under mindvm/agents/<id>/evals/ and flow through source-sync. The CLI’s evals verbs are read + trigger:

mindvm evals list                                 # cases for the current project
mindvm evals run <agent>                          # advisory eval on the agent's pinned suite
mindvm evals runs list                            # recent eval runs
mindvm evals runs get <run-id>
mindvm evals latest <agent>                       # last eval run for this agent

mindvm deploy --run-evals will run the agent’s pinned suite as part of a deploy. Eval results never block deploy — the Phase-12 promotion gate was removed in the 2026-05-11 slim-down.

RAG eval (CI gates)

Two pre-built CI gates over the RAG pipeline, both designed for unattended execution:

mindvm rag-eval formats --gate          # exit non-zero if any supported format fails to index
mindvm rag-eval judge   --gate --pass-threshold 7   # LLM-as-judge against fixture invoices

rag-eval judge requires GEMINI_API_KEY in env (or the equivalent provider key for your judge model). Useful as a smoke test after a schema migration or a chunker tweak.

Scheduled runs

mindvm schedules list
mindvm schedules create --agent <id> --cron "0 9 * * 1" --message "Weekly brief"
mindvm schedules get    <schedule-id>
mindvm schedules delete <schedule-id>

Prompt templates

mindvm templates list
mindvm templates create --name <name> --body @template.md
mindvm templates get    <template-id>
mindvm templates update <template-id> --body @template.md
mindvm templates delete <template-id>

Project + metrics

mindvm show             # project metadata + tier
mindvm metrics          # tokens / agent / eval rollup (billing-dashboard shape)

Output formats and piping

Every command honours --output json. Combine with jq for one-line ops:

# All sessions over the last day that errored
mindvm agents list --output json | \
  jq '.[] | select(.status=="error") | {id, created_at}'

# Trigger an advisory eval on every code-first agent in the project
for agent in $(mindvm config show --output json | jq -r '.agents[].id'); do
  mindvm evals run "$agent"
done

--quiet strips the status banner so --output json lands as clean JSON suitable for piping.

Next steps

• CI integration — mindvm deploy --dry-run and rag-eval --gate patterns for GitHub Actions / GitLab CI / arbitrary shells.
• Interactive TUI — mindvm-tui for chatting with an agent from the terminal.
• SDK overview — programmatic equivalents in Go and TypeScript.
• Tutorials — step-by-step integrator walkthroughs.