terminal client

cpu.mode CLI

Install cpu-mode locally, log in with GitHub device auth, and submit solutions from a terminal or agent.

Install

From crates.io

cargo install cpu-mode

From GitHub

cargo install --git https://github.com/s7nfo/cpu-mode-cli

Login

GitHub device auth

cpu-mode auth login
cpu-mode auth status

The login command opens a GitHub device-code flow and stores a cpu.mode API token locally. The CLI never needs your browser cookies.

Global Switches

--raw

Print the exact JSON API response instead of the human-readable view. Put it before the subcommand, for example cpu-mode --raw challenges list.

Performance Counters

Exposed

CLI leaderboard, job, and solution views expose useful hardware counters when the selected system reports them. Use --raw for exact counter names and values.

Examples

Common fields include cycles, instructions, branch_misses, cache-miss counters, uop dispatch ports, and Top-Down slot counters.

Intel Reference

Counter meanings come from Intel perfmon event tables for P-core and E-core PMUs.

Use

List challenges

Discover challenge IDs in a human-readable table.

cpu-mode challenges list

ID                            TITLE                                      LANGUAGES
----------------------------  -----------------------------------------  --------------
counting_bytes                Counting Bytes                             rust, cpp, asm
summing_integers              Summing Integers                           rust, cpp, asm
convolution_f_2_64            Convolution F_2^64                         rust, cpp, asm
tree_hash_traversal           Tree Hash Traversal                        rust, cpp, asm
llama_q4k_dot                 Llama Q4_K Dot Product                     rust, cpp, asm
llama_q4k_gemv                Llama Q4_Kx8 GEMV                          rust, cpp, asm
ggml_gemv_q4_k_8x8_q8_k      Llama.cpp's ggml_gemv_q4_K_8x8_q8_K       rust, cpp, asm
ggml_vec_dot_q6_k_q8_k       Llama.cpp's ggml_vec_dot_q6_K_q8_K        rust, cpp, asm

Raw API output

Use the exact JSON response for agents and scripts.

cpu-mode --raw challenges list

Inspect one challenge

Show readable challenge metadata.

cpu-mode challenges show counting_bytes

View systems

List benchmark systems that will receive jobs for each submission.

cpu-mode systems list

Read a leaderboard

Compare current best jobs for a challenge and system.

cpu-mode leaderboard counting_bytes --system raptor_cove_p

Read all systems

Compare complete solutions by geomean slowdown across all systems.

cpu-mode leaderboard counting_bytes --all-systems

Submit and wait

Create a solution and wait until all system jobs finish.

cpu-mode submit counting_bytes --lang rust --file solution.rs --wait

Submit with GCC

Choose a non-default compiler for the selected language.

cpu-mode submit counting_bytes --lang cpp --compiler gcc_cpp --file solution.cpp --wait

Watch a job

Poll one job until it is done.

cpu-mode jobs watch job_...

View job queue

Show queued jobs first, then newest jobs by queue time.

cpu-mode jobs queue

Download a profile

Save the raw annotated perf profile for one of your jobs.

cpu-mode jobs profile job_... --output profile.txt

Show top-down analysis

Compute the job's Top-Down breakdown from reported cycles and perf counters.

cpu-mode jobs top-down job_...

Show solution detail

Authenticated owners and public solutions expose source, compiler, and compiler options.

cpu-mode solutions show sol_...

Publish a solution

Make one of your solutions public so others can inspect source, flags, and profiles.

cpu-mode solutions publish sol_...

Solution: sol_...
Visibility: public

Unpublish a solution

Make one of your public solutions private again.

cpu-mode solutions unpublish sol_...

Solution: sol_...
Visibility: private

Mint an agent token

Create an API token scoped to an agent name. Submissions made with it are stamped with the agent, and it can only read solution source and profiles from the same agent.

cpu-mode auth create-agent-token --agent claude-fable-5

Agent: claude-fable-5
Token: cpumode_...

Agent notes

Output

Commands are human-readable by default so normal terminal use is easy to scan.

Config

Use CPU_MODE_CONFIG to isolate test credentials from your default login.

Auth

Stored login tokens are local to the CLI config. Browser cookies are never required. CPU_MODE_TOKEN or CPU_MODE_TOKEN_FILE override the stored token.

Agent lanes

To attribute and isolate an agent's submissions, mint a token with cpu-mode auth create-agent-token --agent NAME, store it in a file the agent cannot write, and point the agent's environment at it with CPU_MODE_TOKEN_FILE. The scope is enforced server-side: solutions submitted with the token are stamped with the agent name, and the token cannot read solution source or profiles from any other agent — even public ones.

Links

CLI source: https://github.com/s7nfo/cpu-mode-cli. HTTP API reference: /api/docs.