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 init --profile default --api-url https://api.messyvirgo.com
messyvirgo auth status --json

auth init uses the same wallet login flow as auth login, but makes profile setup explicit. --profile default --api-url https://api.messyvirgo.com creates or updates the default profile and switches the stored currentProfile to default after browser approval completes. 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 init --profile default --api-url https://api.messyvirgo.com --start --json
# show Approval URL and User code to the user, wait for browser approval
messyvirgo auth init --complete --json
messyvirgo auth status --json

Use messyvirgo auth init --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.

To sign out on this machine and revoke the stored token on the server:

messyvirgo auth logout
messyvirgo auth logout --profile default --json

You can also revoke any approved CLI session from Account Settings in the web app (CLI sessions), including logins from other machines.

The default connection mode is profile mode. Profile selection is --profile, then MESSYVIRGO_PROFILE, then the stored current profile, then default.

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 use default
messyvirgo config get
messyvirgo config list

Agents and automation that cannot use stored profiles may set MESSYVIRGO_ACCESS_TOKEN. That activates env override mode; MESSYVIRGO_API_URL is optional in that mode and defaults to production when omitted. A URL env var without MESSYVIRGO_ACCESS_TOKEN is ignored.

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, validation instructions, and approved CLI runtime metadata. Generated skills use a pinned command such as npx -y @messyvirgo/cli@<approved-version> for runtime commands. Rerun setup to refresh that pin when the approved CLI version changes.

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 use target_candidate_count, rank cross-screen candidates first, fill remaining ranks from strongest single-source evidence unless explicitly saving fewer, 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

upgrade reports the exact version resolved by the update check and recommends exact-version commands such as npm install -g @messyvirgo/[email protected]. --apply executes only for supported global npm installs when an exact version is available. Unsupported install methods, npx-managed runs, and no-version checks 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