Versalist CLI | Versalist Documentation

Command

versalist

The core interface for listing, starting, submitting, and MCP mode.

Best fit

Repo-first workflows

Use the CLI when the work will happen in your local project, not just in the browser.

Auth model

VERSALIST_API_KEY

Required for authenticated start and submit flows.

MCP entry

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

Product identity

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.

Browse

List published challenges

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

Seed

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.

Submit

Create run records

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

Expose

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_...

Scope

read:challenges

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

Scope

submit:solutions

Needed for creating challenge submissions from the CLI.

Scope

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.

List and choose the challenge

Use search or filters before you start pulling context into the repo.

Seed the local workspace

Write the challenge brief and metadata into the project so the rest of the tooling can see it.

Build in your normal environment

Prompt, code, or evaluate in the same repo where you already do the work.

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.