The core command is versalist, the interface for listing, starting, submitting, and MCP mode. The CLI is the best fit for repo-first workflows where the work will happen in your local project, not just in the browser. Authenticated start and submit flows require a VERSALIST_API_KEY, and versalist mcp exposes Versalist through the CLI for editor and agent hosts.

Quick start

Install the CLI package once, then use the short versalist command in any repo or shell session.

npm install -g @versalist/cli
versalist list
versalist start dspy-optimization-challenge

One-off usage

If you do not want a global install, use the package through npx or the explicit npm exec form.

npx -y @versalist/cli list
npx -y @versalist/cli start dspy-optimization-challenge

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

The CLI is a first-class interface, not a thin wrapper around the site. Use it when the challenge work belongs in a repo, editor, or agent host. The CLI gives you the same challenge loop in a form that makes sense for local execution, while MCP mode is one specific CLI mode for tool-connected environments.

What the CLI is best at

The CLI is designed for the high-signal parts of the workflow: pick the task, seed the local context, build in your repo, then submit without re-entering the same information in the browser.

List published challenges

Use the terminal to discover challenges before you commit to opening the browser detail page.

Write the challenge into the repo

Start mode writes the challenge brief and metadata into the current working directory so local tools can use it.

Create run records

Submit from the same local context where the work happened, which keeps the workflow tighter and easier to compare later.

Run MCP mode

Use MCP mode when you want Versalist available inside an editor or agent host rather than only in the shell.

What happens after submit

versalist submit creates a project submission for the active challenge. It does not automatically run every possible in-app evaluation or scoring path for you. When a challenge has richer run or evaluation surfaces, use the detail page to continue from that submission record.

Core commands

versalist list

Browse published challenges directly from the terminal. Use search, category, difficulty, and JSON output when you want the terminal to be the source of truth for selection.

versalist list
versalist list --search reranker
versalist list --category evaluation --difficulty advanced
versalist list --page 2 --limit 12
versalist list --json

versalist start <slug-or-id>

Start writes the challenge into your current working directory so your editor, agent, or automation can reason against local files instead of only browser state.

versalist start dspy-optimization-challenge

The command creates:

• CHALLENGE.md with the full brief
• .versalist.json with challenge metadata for later CLI commands
• eval/examples.json when public gold examples are available

versalist submit

Submit a run from the current repo context. If your primary artifact URL is not GitHub, pass a separate repository URL with --github-url.

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

Common flags:

• --challenge overrides the challenge in .versalist.json
• --description adds implementation notes
• --model and --toolchain attach agent benchmarking metadata

versalist mcp

Start the Versalist MCP server over stdio when you want the same challenge surface available inside an editor or agent host.

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

API key requirements

versalist list can browse public challenge data without authentication. For versalist start and versalist submit, export a user API key first.

export VERSALIST_API_KEY=vk_live_...

read:challenges

Needed for loading challenge detail and markdown when you move beyond simple public listing.

submit:solutions

Needed for creating challenge submissions from the CLI.

read:submissions

Useful for richer submission lookup workflows as your tooling becomes more advanced.

A clean operator loop

This is the core terminal-native workflow the CLI is designed to support.

1. List and choose the challenge. Use search or filters before you start pulling context into the repo.
2. Seed the local workspace. Write the challenge brief and metadata into the project so the rest of the tooling can see it.
3. Build in your normal environment. Prompt, code, or evaluate in the same repo where you already do the work.
4. Submit from the same context. Create the run record only after the project already has the right implementation context attached.

$ versalist list --search dspy
01. DSPy Optimization Challenge
    slug: dspy-optimization-challenge | category: evaluation | difficulty: advanced

$ versalist start dspy-optimization-challenge
[ok] Wrote CHALLENGE.md
[ok] Wrote .versalist.json
[ok] Wrote eval/examples.json (6 public example(s))

$ versalist submit --url https://github.com/you/dspy-run --title "Reranker v2"
[ok] Submission received

CLI and MCP mode

The CLI serves two roles. Use list, start, and submit for direct terminal workflows. Use versalist mcp when a tool-connected editor or agent host needs the same capability surface over stdio.