Messy Virgo CLI

Public command-line interface for Messy Virgo fund, screening, context feeds, and activity workflows.

Install

npx @messyvirgo/cli --help
npm install -g @messyvirgo/cli
messyvirgo --help

Bare messyvirgo renders a compact welcome banner only in an interactive TTY. In non-TTY, JSON, or agent mode it falls back to standard help output.

Auth and Config

The CLI talks to the API over HTTP and uses bearer auth.

Preferred authentication is browser wallet approval:

messyvirgo auth login
messyvirgo auth status --json

auth login stores a principal-bound machine token in the selected private CLI config store. By default this is local user config outside the repository. Workspace-scoped assistants that cannot write user-level config can set MESSYVIRGO_CONFIG_HOME="$PWD/.messy/auth" before running CLI commands; keep that directory gitignored. The browser login code expires quickly, but the stored token remains usable until logout or server-side revocation.

Assistants that cannot keep a long-running login process alive should use the resumable flow:

messyvirgo auth login --start --json
# show Approval URL and User code to the user, wait for browser approval
messyvirgo auth login --complete --json
messyvirgo auth status --json

Use messyvirgo auth login --cancel --json to clear a pending login without removing an already stored token. If --start --json reports AUTH_LOGIN_ALREADY_STARTED, approve the returned URL or cancel the pending login before starting a new one.

Environment variables remain available for local development and automation:

• MV_API_URL: API base URL.
• MESSYVIRGO_ACCESS_TOKEN: preferred non-interactive assistant token for hosted or sandboxed hosts.
• MV_API_KEY: legacy service-token override (mvk_...) for local development and older automation.

You can also persist values in a profile manually:

messyvirgo config set api-url https://api.messyvirgo.com
messyvirgo config set api-key mvk_...
messyvirgo config get

Resolution order is: command flags -> environment -> profile config.

Agent-first Contract

Agents should use flags and --json instead of prompts:

MESSYVIRGO_AGENT=1 messyvirgo auth status --json
MESSYVIRGO_AGENT=1 messyvirgo funds list --json

MESSYVIRGO_AGENT=1, non-TTY stdout, or --json suppresses banners, update notices, and interactive prompts.

Errors in JSON mode use:

{
  "error": {
    "code": "MISSING_ASSISTANT_INSTALL_INPUT",
    "message": "Human readable message",
    "details": {},
    "status_code": 400
  }
}

Assistant Setup

Agent Tools installation is served by the API setup homepage, not by CLI lifecycle commands. For copyable user-facing instructions, see agentic/agent-tools/docs/installation.md.

Tell a local assistant:

Install Messy Virgo Agent Tools from https://api.messyvirgo.com/assistant/setup

For local API testing, use:

Install Messy Virgo Agent Tools from http://localhost:8000/assistant/setup

The setup homepage returns target-specific install, update, uninstall, authentication, and validation instructions. The generated skills use npx -y @messyvirgo/cli@latest for runtime commands.

JSON Output

Structured commands already return JSON-shaped output by default. Use --json when you want that machine-readable contract made explicit:

messyvirgo funds list --json
messyvirgo screening templates list --json

For commands that accept JSON payloads, pass --file path/to/payload.json or pipe JSON with --file -:

messyvirgo screening workflow run mvf-example mvs-example --run-date 2026-05-01 --json
messyvirgo screening runs create mvf-example --file ./run.json --json
cat ./run.json | messyvirgo screening runs create mvf-example --file - --json

screening workflow run treats template/query preview rows as evidence. It does not persist a run or select final candidates. The outer agent or operator must select candidates, assign ranks, and write evidence-grounded candidate_reason text before calling screening runs create.

Update Awareness and Upgrade

In interactive TTY mode, the CLI can print a non-blocking update notice after command completion. It is suppressed by MESSYVIRGO_AGENT=1, NO_UPDATE_NOTIFIER=1, --json, --no-update-check, and non-TTY stdout.

Use upgrade to inspect or apply the recommended upgrade path:

messyvirgo upgrade
messyvirgo upgrade --apply --json

--apply executes only for supported global npm installs. Unsupported install methods print manual instructions and exit zero.

Command Groups

• messyvirgo funds ... - list funds and inspect fund status, performance, sleeves, and activity
• messyvirgo screening ... - execute sleeve screening and manage context, templates, single-day runs, aggregate runs, KPIs, and scores
• messyvirgo context ... - get current context snapshots
• messyvirgo context macros ... - get macro context, scores, and KPIs
• messyvirgo context narratives ... - list or get narrative momentum snapshots
• messyvirgo config ... - read or set persisted CLI config values
• messyvirgo upgrade - print or run the recommended CLI upgrade command

Local Development

cd services/cli
npm install
npm run build
npm test

Runbook

• docs/runbooks/command-line-interface.md