Versalist CLI

Versalist ships as both:

• a CLI with the versalist command
• an MCP server for Claude Code, Cursor, Windsurf, and other MCP-compatible tools

Namespace summary:

• npm package: @versalist/cli
• installed CLI command: versalist
• MCP subcommand: versalist mcp
• MCP server name: versalist

Install

Install the Versalist CLI:

npm install -g @versalist/cli

After install, use the short command:

versalist list
versalist start dspy-optimization-challenge

If you want one-off usage without installing globally:

npx -y @versalist/cli list

If your shell host or wrapper has trouble resolving the package bin through npx, use the explicit form:

npm exec --yes --package @versalist/cli versalist list

CLI

Set your API key for authenticated commands:

export VERSALIST_API_KEY=vk_live_...

Browse challenges:

versalist list
versalist list --search reranker
versalist list --category evaluation --difficulty advanced

Seed the current repo with challenge context:

versalist start dspy-optimization-challenge

This writes:

• CHALLENGE.md
• .versalist.json
• eval/examples.json when public examples are available

Submit a run:

versalist submit --url https://github.com/you/solution --title "Reranker v2"

versalist submit creates a project submission for the challenge. Automated scored runs happen in the web app's Run tab for challenges that support episode evaluation.

MCP usage

Example Claude Code config:

{
  "mcpServers": {
    "versalist": {
      "command": "npx",
      "args": ["-y", "@versalist/cli", "mcp"],
      "env": {
        "VERSALIST_API_KEY": "vk_live_..."
      }
    }
  }
}

Recommended:

versalist mcp

Backwards compatibility:

npx -y @versalist/cli mcp

Explicit fallback for environments where npx bin inference is flaky:

npm exec --yes --package @versalist/cli versalist mcp

Running the package with no CLI arguments still starts the MCP server over stdio for backwards compatibility.

Environment variables

• VERSALIST_API_KEY: required for versalist start and versalist submit
• VERSALIST_BASE_URL: optional, defaults to https://versalist.com

Docs

• CLI docs: https://versalist.com/docs/cli