Command reference

Conventions

Commands that take <slug|file> accept a problem’s slug, its id, or the path of one of your solution files; the path also sets the language. Where the argument is optional, they act on the active attempt: your most recent attempt in progress. Every command but init, doctor, list and show needs a workspace.

Global options go before the command:

Global options
Option	Effect
`--version`	Print the version and exit
`--workspace PATH`	The workspace; default: CSTUDY_WORKSPACE, the nearest one above the current directory, or here
`--content PATH`	Read problems, tracks and runners from this checkout; default: CSTUDY_CONTENT, else the bundled content
`--no-color`	Plain output; also when NO_COLOR is set or the output is not a terminal

shell

cstudy --workspace ~/cstudy-workspace start two-sum

cstudy init

usage

cstudy init [PATH] [--git] [--force] [--ide vscode|idea]... [--no-ide]

Creates a workspace in PATH (default: the current directory), with the practice projects, the editor files and the runner runtime. It installs nothing; run cstudy doctor --fix next. It refuses a directory that already is, or is inside, a workspace.

cstudy init options
Option	Effect
`--git`	Run git init there; cstudy never commits
`--ide vscode\|idea`	Write only this editor’s project files; repeatable. Default: both
`--no-ide`	Write no editor project files
`--force`	Allow a workspace inside a cstudy source checkout

cstudy doctor

usage

cstudy doctor [--fix]

Checks the toolchains, the configuration file and the workspace, one line per check: ok, WARN or FAIL, with a fix where one applies. Exits 0 when nothing fails, 4 otherwise.

cstudy doctor options
Option	Effect
`--fix`	In a workspace: write missing template files, refresh the runner runtime, then run `uv sync`, `pnpm install` and the Gradle warm-up. Never overwrites your files

terminal

$ cstudy doctor
ok    python 3.13.2
ok    uv 0.10.11
ok    node v24.18.0 (type stripping)
ok    pnpm 9.15.9
ok    java 21.0.2
ok    content /home/me/.local/share/uv/tools/coding-study/lib/python3.13/site-packages/coding_study/content (bundled)
ok    workspace /home/me/ws (created with cstudy 0.1.0)
FAIL  python/.venv missing    fix: cstudy doctor --fix
ok    runner python answers hello: python 3.13.2, protocol 1
ok    runner kotlin answers hello: jvm 21.0.2, protocol 1

cstudy ide

usage

cstudy ide [vscode|idea|all] [--force]

Writes or refreshes the VS Code and IntelliJ IDEA project files (default: both). Files you edited are kept, with a warning. See Editors and debugging.

cstudy ide options
Option	Effect
`--force`	Also overwrite the editor files you edited

terminal

$ cstudy ide
ide      vscode, idea · 1 updated · 1 kept
warning  kept .vscode/tasks.json: edited, or not written by cstudy (cstudy ide --force overwrites it)

cstudy next

usage

cstudy next [--track T]... [--pattern P] [--difficulty D] [--lang L] [--new | --review] [--start]

Picks what to practise: a due review, or a new problem from your weakest group, and prints the command to start it. See What cstudy next picks.

cstudy next options
Option	Effect
`--track T`	Only this track; repeatable. Default: next.tracks in your configuration (dsa)
`--pattern P`	Problems that list this pattern
`--difficulty D`	easy, medium or hard
`--lang L`	Problems available in this language; the language to start in
`--new`	Skip reviews
`--review`	Skip new problems
`--start`	Run cstudy start on the pick

terminal

$ cstudy next
new     koko-eating-bananas  (medium · binary-search)  weakest pattern: binary-search (0.75)
start   cstudy start koko-eating-bananas --lang kotlin

cstudy start

usage

cstudy start <slug|file> [--lang L] [--fresh] [--timer DURATION] [--no-open] [--restore PATH]

Writes or reopens the stub, renders the statement, begins an attempt and opens both files in your editor. Starting a problem already in progress in the same language resumes it.

cstudy start options
Option	Effect
`--lang L`	Language; default: default_lang
`--fresh`	Archive the existing file and write a new stub
`--timer DURATION`	A time box, such as 25m or 1h; finishing over it caps the grade at hard
`--no-open`	Do not launch the editor
`--restore PATH`	Project problems: write one starter file or generated test file back, and do nothing else

terminal

$ cstudy start two-sum --lang kotlin
two-sum · easy · arrays-hashing · kotlin
stub       jvm/kotlin/src/main/kotlin/practice/two_sum/Solution.kt
statement  .statements/two-sum.md
next       cstudy test --watch

cstudy test

usage

cstudy test [<slug|file>] [--lang L] [--watch] [--case ID]... [--all] [--level N]
        [--time-limit[=VALUE] | --no-time-limit] [--perf] [--typecheck] [--stress N] [--seed S]
        [--json | --events] [--debug [--debug-port N] [--debug-connect]]

Runs your code against the cases of the problem; for a project problem, its own test suite. Exits 0 when every case passed, 1 when one did not, 2 when your code did not build or load.

cstudy test options
Option	Effect
`--lang L`	Language; default: the attempt’s
`--watch`	Run again on every save
`--case ID`	Run only these cases; repeatable
`--all`	Print every case, including passing hidden ones
`--level N`	Progressive and project problems: run levels 1 to N (open levels only)
`--time-limit[=VALUE]`	Turn time limits on; `VALUE` is a factor of the reference time such as `5x`, or an absolute limit such as `1500ms`. The value only follows `=`
`--no-time-limit`	Turn time limits off, even if your configuration turns them on
`--perf`	After all cases pass, run a short bench and print its verdict
`--typecheck`	TypeScript: also run tsc --noEmit
`--stress N`	1 to 100. Concurrent problems: runs per stress case and variant. Function and design problems: also check N generated inputs against the oracle
`--seed S`	Base seed: run r, or oracle input r, uses S + r. Needs --stress for non-concurrent problems
`--json`	One JSON document instead of the report
`--events`	Project problems: the run as JSON events, one per line
`--debug`	Wait for a debugger to attach to the runner, with time limits off
`--debug-port N`	With --debug: the agent’s port. Defaults: Python 5678, TypeScript 9229, Java and Kotlin 5005, Go 2345, Rust 12345
`--debug-connect`	With --debug, Java and Kotlin: connect to an IDE that is already listening

terminal

$ cstudy test --time-limit
two-sum · kotlin · 14 cases (2 visible, 11 hidden, 1 generated) · time limit 5x · timer 12:31 / 25:00
build  1.8s (gradle, warm)

PASS     ex1   0.04ms
PASS     ex2   0.03ms
FAIL     h3    hidden
         input     nums=[-3, 8, 0, 3]  target=0
         expected  [0, 3]  (unordered)
         actual    [3, 3]
TLE      g1    hidden · 412ms > limit 95ms (5x hash-map, calibrated)
PASS     10 hidden cases

12/14 passed · 1 failed · 1 tle · total 2.6s

cstudy submit

usage

cstudy submit [<slug|file>] [--level N] [--json | --events]

Grades a project problem: every case of the open levels, visible and hidden. A submission that passes them all opens the next level. See Project problems.

cstudy submit options
Option	Effect
`--level N`	Grade levels 1 to N (open levels only); a lower N opens nothing
`--json`	One JSON document instead of the report
`--events`	The run as JSON events, one per line

terminal

$ cstudy submit
bank-project-python · python · submit levels 1-2 of 4 · timer 33:05 / 90:00

level 1  PASS     5/5 (2 visible, 3 hidden)
level 2  FAIL     4/5 (2 visible, 3 hidden)
FAIL     h3    hidden · level 2
         input     ops ["Bank", "create_account", ...]  args [[], [1, "zoe"], ...]
         expected  ["abe(60)", "zoe(60)", "mia(0)"]
         actual    ["zoe(60)", "abe(60)", "mia(0)"]

9/10 passed · level 3 opens when levels 1-2 pass

cstudy status

usage

cstudy status [<slug|file>] [--json]

Shows where a project problem’s attempt stands: open level, timer, latest test and submission, and changed files.

cstudy status options
Option	Effect
`--json`	One JSON document instead of the report

terminal

$ cstudy status
bank-project-python · python · project · attempt 41 · new
level      2 of 4: Top spenders (opened 18:02)
timer      33:05 / 90:00
tested     3/4 passed, 1 min ago
submitted  level 1 5/5 · level 2 4/5, 2 min ago
files      2 changed, 1 added, 0 removed against the starter
next       cstudy submit once level 2 passes

cstudy hint

usage

cstudy hint [<slug|file>]

Reveals the next hint and counts it on the attempt; any hint caps the grade at ok. Prints no more hints when there are none left. Locked during a mock interview.

terminal

$ cstudy hint
two-sum · hint 1 of 2
For each value, which partner would complete the sum?

cstudy solution

usage

cstudy solution <slug|file> [--lang L] [--approach ID] [--all] [--broken[=ID]] [--explanation-only] [--yes]

Shows the reference solutions with their explanations, through your pager; by default the first optimal approach. Before your attempt passes, it asks first, since revealing grades the attempt as again. Locked during a mock interview.

cstudy solution options
Option	Effect
`--lang L`	Language of the reference code
`--approach ID`	This approach only
`--all`	Every approach, in ladder order
`--broken[=ID]`	Concurrent problems: a deliberately broken reference, as a spot-the-bug exercise
`--explanation-only`	Explanations without code
`--yes`	Reveal without asking, even before a pass

cstudy done

usage

cstudy done [<slug|file>] (--rating easy|ok|hard | --gave-up) [--notes TEXT]

Finishes the attempt, computes its grade and schedules the next review. See Finishing an attempt.

cstudy done options
Option	Effect
`--rating easy\|ok\|hard`	How it went; required after a full pass
`--gave-up`	Finish without a full pass; the grade is again
`--notes TEXT`	Notes kept on the attempt

terminal

$ cstudy done --rating ok
two-sum · kotlin · passed · 18m 40s · rating ok · hints 0
next review  2026-10-27 (in 3 days) · ease 2.50

cstudy bench

usage

cstudy bench [<slug|file>] [--lang L] [--sizes LIST] [--reps N] [--refs-only] [--no-memory]

Measures how your solution scales and compares it with the reference approaches. Not available for concurrent or project problems. See Checking performance.

cstudy bench options
Option	Effect
`--lang L`	Language; default: the attempt’s
`--sizes LIST`	Comma-separated sizes, such as 100,1000,10000
`--reps N`	Timed repetitions per size (default 7)
`--refs-only`	Bench the references only
`--no-memory`	Skip the memory measurements

terminal

$ cstudy bench
two-sum · python · sizes 1e2..1e5 · reps 7 · power AC · load 1.2

TARGET        DECLARED   n=1e2    n=1e3    n=1e4    n=1e5    SLOPE  BAND     MEMORY
brute-force   O(n^2)     0.21ms   19.8ms   2.04s    budget   2.00   ~n^2     constant
hash-map      O(n)       0.01ms   0.09ms   0.94ms   10.1ms   1.00   ~n|nlogn linear
you                      0.01ms   0.11ms   1.10ms   11.8ms   1.01   ~n|nlogn linear

verdict   optimal: matches hash-map, 1.17x at n=1e5 · confidence high (spread 3%, R^2 0.999)
space     linear, same as hash-map · confidence high
history   best previous 13.0ms at n=1e5 (2026-09-12) · now 9% faster · 1st of 3 runs

cstudy mock

usage

cstudy mock [--minutes 45] [--count 2] [--track T]... [--lang L]

Starts a timed mock interview: new medium and hard problems with one shared timer, with hints and solutions locked until the timer ends or every problem is done.

cstudy mock options
Option	Effect
`--minutes N`	The shared timer (default 45)
`--count N`	How many problems (default 2)
`--track T`	Only this track; repeatable. Default: next.tracks
`--lang L`	Language; default: default_lang

terminal

$ cstudy mock
mock interview · 2 problems · 45 min shared timer · python
1  group-anagrams  (medium · arrays-hashing)  weakest pattern: arrays-hashing (0.75)
   stub       python/practice/group_anagrams.py
   statement  .statements/group-anagrams.md
2  lru-cache  (medium · linked-list)  weakest pattern: linked-list (0.75)
   stub       python/practice/lru_cache.py
   statement  .statements/lru-cache.md
locked     cstudy hint and cstudy solution, until the timer ends or every problem is done
next       cstudy test group-anagrams --watch

cstudy list

usage

cstudy list [--track T] [--pattern P] [--difficulty D] [--status S] [--content draft|ready] [--lang L]

Browses the catalog, with your status and next review date for each problem.

cstudy list options
Option	Effect
`--track T`	Only this track
`--pattern P`	Problems that list this pattern
`--difficulty D`	Only this difficulty
`--status S`	new, attempted, passed, due or mastered
`--content draft\|ready`	Content status
`--lang L`	Problems with a reference in this language

terminal

$ cstudy list
ID    SLUG              DIFF    PATTERN          STATUS    DUE         REFS
0001  two-sum           easy    arrays-hashing   passed    2026-10-27  py ts java kt
0002  lru-cache         medium  linked-list      new       -           py ts java kt
0014  koko-eating-...   medium  binary-search    due       2026-10-21  py java

cstudy show

usage

cstudy show <slug|file> [--level N]

Prints the rendered statement, never the hints. For a progressive or project problem it shows the open levels.

cstudy show options
Option	Effect
`--level N`	Show levels 1 to N (open levels only)

cstudy stats

usage

cstudy stats [--by pattern|track|lang|difficulty] [--since DATE] [--json]

Summarises your progress per group, with your streak, the reviews due and your latest bench verdicts.

cstudy stats options
Option	Effect
`--by`	Group by pattern (the default), track, lang or difficulty
`--since DATE`	Only attempts and bench runs since DATE (YYYY-MM-DD)
`--json`	The same values as one JSON document

terminal

$ cstudy stats
GROUP           PROBLEMS  ATTEMPTED  PASSED  MASTERED  PASS RATE  SOLVE TIME  WEAKNESS
arrays-hashing        17          5       4         1        80%     14m 10s      0.42
two-pointers          10          0       0         0          -           -      0.75
system-design         10          1       1         0       100%     45m 00s      0.30

attempts  6 finished · 5 in the last 7 days · streak 3 days
reviews   1 due today · 1 overdue
bench     4 benched · 2 optimal · 1 near-optimal · 1 suboptimal · 0 unknown

cstudy export

usage

cstudy export [--out PATH]

Writes your progress as JSON, by default to progress-export.json at the workspace root, one row per line so a committed export diffs cleanly.

cstudy export options
Option	Effect
`--out PATH`	Where to write the export; an existing file is replaced

terminal

$ cstudy export
exported  attempts 6 · test_runs 4 · schedule 3 · bench_runs 3
file      progress-export.json

cstudy import

usage

cstudy import [PATH]

Restores an export (default: progress-export.json) into a progress.db that has no progress yet. It never merges.

terminal

$ cstudy import
imported  attempts 6 · test_runs 4 · schedule 3 · bench_runs 3
into      progress.db

cstudy new

usage

cstudy new <slug> [--track T] [--from-template TEMPLATE] [--title TEXT] [--difficulty D] [--pattern P]

Scaffolds a problem of your own in the workspace’s problems/, as a draft. Templates: array (default), tree, design, progressive, concurrent, and project-python, project-typescript, project-go, project-java, project-kotlin, project-rust. See Writing your own problems.

cstudy new options
Option	Effect
`--track T`	dsa, practical, lld, concurrency or debugging; default: the template’s
`--from-template TEMPLATE`	The shape to start from
`--title TEXT`	Title; default: from the slug
`--difficulty D`	Difficulty; default: medium
`--pattern P`	Primary pattern; default: the template’s

cstudy verify

usage

cstudy verify [<slug>...] [--changed] [--track T] [--lang L] [--static]
          [--oracle [--oracle-cases N]] [--ladder] [--conformance] [--require-ready] [--jobs N] [--stress N]

Checks problems: their files statically, then every reference solution against the cases in every language. Without slugs, every problem.

cstudy verify options
Option	Effect
`--changed`	Only problems with files changed from main (git)
`--track T`	Only this track
`--lang L`	Only this language
`--static`	Schema and static checks only; nothing runs
`--oracle`	Cross-check every approach against the oracle
`--oracle-cases N`	Oracle inputs (default 200)
`--ladder`	Bench the references and check their growth against the declared complexity
`--conformance`	Run the runner conformance suite
`--require-ready`	Fail any problem that is not ready
`--jobs N`	Parallel language runners
`--stress N`	Concurrent problems: runs per stress case and variant (default 10)

terminal

$ cstudy verify
0001-two-sum      static ok · py 2/2 ok · ts 1/1 ok · java 1/1 ok · kt 1/1 ok · oracle 200/200
0014-koko-eat...  static ok · py 2/2 ok · ts - · java 1/1 ok · kt -      draft (coverage 2/4)
0031-word-break   FAIL static: solutions/explanation.md missing "### Correctness" in approach memo-dp
0190-bounded-...  static ok · py 2/2 ok · ts 1/1 ok · java 2/2 ok · kt 2/2 ok · stress 10/10 · slowest 8% · broken caught 11/11

coverage  python 31/31 · typescript 29/31 · java 31/31 · kotlin 28/31
result    1 failed · 30 passed

Configuration

One optional file holds your preferences: ~/.config/coding-study/config.toml (under $XDG_CONFIG_HOME when set; CSTUDY_CONFIG overrides the path). Every key is optional; these are the defaults. A command-line flag always wins over the file.

config.toml

default_lang = "python"          # python | typescript | java | kotlin | go | rust
open_on_start = true             # run $VISUAL or $EDITOR on cstudy start
progress_db = "progress.db"      # relative to the workspace root

[next]
tracks = ["dsa"]

[time_limit]
enabled = false                  # time limits are off unless enabled here or by flag
# value = "5x"                   # unset by default, so the problem's own value applies
floor_ms = 100

[hang_guard]
# ms = 10000                     # unset by default, so case and problem values apply, then 10000

[bench]
reps = 7
memory = true

[schedule]
penalize_suboptimal = true
max_interval_days = 180

[study_guides]
# root = "~/study-guides"        # unset by default: no study-guide links

Environment variables

Environment variables cstudy reads
Variable	Effect
`CSTUDY_WORKSPACE`	The workspace, when --workspace is not given
`CSTUDY_CONTENT`	A content checkout, when --content is not given
`CSTUDY_CONFIG`	The path of the configuration file
`VISUAL, EDITOR`	The editor cstudy start opens
`PAGER`	The pager cstudy solution uses
`NO_COLOR`	Plain output

Exit codes

Exit codes and what they mean
Code	Meaning
0	Success; all cases passed
1	Test or verify failures, including timeouts and time limits
2	Your code failed to build or load
3	Usage error: bad flags, unknown slug, no active attempt
4	Environment error: a toolchain is missing, or a runner did not start
5	Content error: a problem’s files failed a schema or static check
70	Internal error in cstudy
130	Interrupted

The CLI spec defines every command, output line and JSON field in full.

Conventions#

cstudy init#

cstudy doctor#

cstudy ide#

cstudy next#

cstudy start#

cstudy test#

cstudy submit#

cstudy status#

cstudy hint#

cstudy solution#

cstudy done#

cstudy bench#

cstudy mock#

cstudy list#

cstudy show#

cstudy stats#

cstudy export#

cstudy import#

cstudy new#

cstudy verify#

Configuration#

Environment variables#

Exit codes#

Conventions

cstudy init

cstudy doctor

cstudy ide

cstudy next

cstudy start

cstudy test

cstudy submit

cstudy status

cstudy hint

cstudy solution

cstudy done

cstudy bench

cstudy mock

cstudy list

cstudy show

cstudy stats

cstudy export

cstudy import

cstudy new

cstudy verify

Configuration

Environment variables

Exit codes