@messyvirgo/cli

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.

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/cli@0.24.0. --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