cg puzzle¶

Every cg puzzle subcommand.

Every command also accepts -h / --help.

Command	Summary
`cg puzzle`	Puzzle working directory commands--solve an existing CodinGame puzzle locally.
`cg puzzle import`	Build a fresh puzzle working directory: resolve PUZZLE to a real puzzle (in order of preference: a numeric puzzle ID; an exact pretty ID, e.g.
`cg puzzle repair`	Reconstruct .meta/ (gitignored server-derived cache: the test session handle, plus read-only statement.html/stub_generator.cgstub reference copies) from puzz...
`cg puzzle submit`	Submit the current local solution.src to the server for credit (TestSession/submit)--a real, permanent graded submission, unlike `cg puzzle play-server`.
`cg puzzle play-server`	Run the current local solution.src against one or more of the puzzle's test cases via the server (TestSession/play--the IDE's "Test" button, not a real submi...
`cg puzzle play`	Run the current local solution.src against the downloaded .meta/tests/ test cases entirely locally (no network access at all)--by shelling out to the appropr...
`cg puzzle description`	Display the puzzle's problem statement, rendered from the cached .meta/statement.html (no network access--run `cg puzzle import`/`repair` first if missing).
`cg puzzle diff`	Show a unified diff between the local solution.src and the server's current last-submitted answer for this puzzle.
`cg puzzle status`	Human-friendly summary of this puzzle: title, language, and local-edit status.
`cg puzzle discard-local`	Discard local edits: overwrite solution.src with the server's current last-submitted answer for this puzzle.
`cg puzzle debug`	Debug-session plumbing for languages whose debugger attaches to a running target (C++, via gdbserver in its container).
`cg puzzle debug start`	Build the debug profile and start a stopped debug target fed by TEST-INDEX's input, ready for a debugger to attach.
`cg puzzle debug stop`	Stop a debug target started by `cg puzzle debug start`.
`cg puzzle build`	Compile data/solution.src, if its language needs compiling (a no-op for interpreted languages like Python3).
`cg puzzle set-language`	Switch this puzzle to a different language, restoring your own most recent code for it.
`cg puzzle activate`	Make DIRECTORY the active puzzle working directory, so subsequent `cg puzzle` commands use it without needing --puzzle-dir.
`cg puzzle deactivate`	Clear the active puzzle working directory, so `cg puzzle` commands fall back to the configured default and the usual directory discovery.
`cg puzzle select-test`	Choose which test case `cg puzzle debug` (and `cg play --selected`) runs against.
`cg puzzle where`	Show which puzzle working directory would be used.
`cg puzzle delete`	Delete this puzzle working directory. Purely local

`cg puzzle`¶

Puzzle working directory commands--solve an existing CodinGame puzzle locally. Much simpler than cg contribution: exactly one file (data/solution.src) is ever editable, so there's no git repo involved--see codingame_tools.puzzle_manager.manager's module docstring. Currently only classic PUZZLE_INOUT puzzles are supported.

usage: cg puzzle [-h] [--puzzle-dir DIR] COMMAND ...

Options

-d, --puzzle-dir DIR — Working directory to operate on. Defaults to CG_PUZZLE_DIR, then the configured default (cg settings set puzzle-dir), then the current directory or "./puzzle" if it contains puzzle.json.

Subcommands

import — Build a fresh puzzle working directory: resolve PUZZLE to a real puzzle (in order of preference: a numeric puzzle ID; an exact pretty ID, e.g. 'literary-alfabet-soupe'; an exact-matching title; a case-insensitive-matching title), then resolve this codingamer's test session for it (Puzzle/generateSessionFromPuzzlePrettyId), then fetch its current state (TestSession/startTestSession). Imports the codingamer's existing saved answer if there is one, in whatever language it was written in; otherwise seeds a placeholder solution.src in --language. Unlike cg contribution import, uses the normal --puzzle-dir resolution (with a cwd/./puzzle fallback) rather than requiring an explicit new-directory argument--puzzle working directories are expected to be reused across different puzzles over time, one at a time.
repair — Reconstruct .meta/ (gitignored server-derived cache: the test session handle, plus read-only statement.html/stub_generator.cgstub reference copies) from puzzle.json's stable puzzle_id--for recovering after a fresh clone into a different repo (.meta/ is gitignored on purpose) or manual deletion/corruption of .meta/. Never touches data/.
submit — Submit the current local solution.src to the server for credit (TestSession/submit)--a real, permanent graded submission, unlike cg puzzle play-server. Note cg puzzle play-server also durably updates the server's copy of the code as a side effect of running a test case--this command is the one that actually grades it.
play-server — Run the current local solution.src against one or more of the puzzle's test cases via the server (TestSession/play--the IDE's "Test" button, not a real submission; see cg puzzle play for the entirely-local, no-network equivalent). With no TEST-INDEX arguments, runs every downloaded test case (.meta/tests/); give one or more 1-based indices to run just those. Exits 1 if any run errored or didn't match the expected output. Output matches cg puzzle play's format. Captured stdout is only printed for a failing test, unless --show-stdout is given.
play — Run the current local solution.src against the downloaded .meta/tests/ test cases entirely locally (no network access at all)--by shelling out to the appropriate interpreter as a subprocess, comparing captured stdout to each test's expected output (see cg puzzle play-server for the real, server-side equivalent). Currently only Python3 solutions are supported. With no TEST-INDEX arguments, runs every downloaded test case; give one or more 1-based indices to run just those. Exits non-zero if any test case fails. Captured stdout is only printed for a failing test (as part of its diff), unless --show-stdout is given.
description — Display the puzzle's problem statement, rendered from the cached .meta/statement.html (no network access--run cg puzzle import/repair first if missing). Section headers and the Example's input/output text are color-highlighted when writing to a real terminal. With --json (top-level option), prints the parsed [{kind, text}, ...] blocks instead.
diff — Show a unified diff between the local solution.src and the server's current last-submitted answer for this puzzle.
status — Human-friendly summary of this puzzle: title, language, and local-edit status. By default entirely local (no network access); pass --refresh to also check for local edits against the server's last-submitted answer and fetch live progress/score (two live calls--there is no local cache for puzzles, unlike cg contribution status, so this is always genuinely live, every time). With --json (top-level option), renders as JSON instead of text.
discard-local — Discard local edits: overwrite solution.src with the server's current last-submitted answer for this puzzle. Purely local--no network side effect beyond the read.
debug — Debug-session plumbing for languages whose debugger attaches to a running target (C++, via gdbserver in its container). Normally invoked for you by the VS Code tasks cg puzzle vscode generates, not typed by hand. Languages whose debugger launches the program itself--Python3--don't use these at all.
build — Compile data/solution.src, if its language needs compiling (a no-op for interpreted languages like Python3). Normally you don't need this--cg puzzle play builds first automatically--but it's useful to compile without running, or to warm a cold container image up front. Near-instant when the source hasn't changed since the last successful build. Compiler diagnostics go to stderr.
set-language — Switch this puzzle to a different language, restoring your own most recent code for it. CodinGame keeps your latest source per language, so anything you'd previously written in the target language comes back; a language you've never used gets a placeholder. Refuses if data/solution.src holds work the server doesn't have (submit it first, or pass --force to discard it). Changes local state only--the server's current language follows once you run a server-side test or submit in the new one.
activate — Make DIRECTORY the active puzzle working directory, so subsequent cg puzzle commands use it without needing --puzzle-dir. Set automatically by cg puzzle import, so this is for switching between working directories you already have. Outranks the configured default (cg settings set puzzle-dir); cg puzzle deactivate clears it.
deactivate — Clear the active puzzle working directory, so cg puzzle commands fall back to the configured default and the usual directory discovery. Does not touch any files--only the selection.
select-test — Choose which test case cg puzzle debug (and cg play --selected) runs against. Debugging feeds one stdin, so it needs exactly one test. Recorded in .meta/selected-test.json rather than in launch.json, which is what lets one VS Code debug configuration serve every puzzle directory instead of being regenerated per directory. With no INDEX, shows the current selection.
where — Show which puzzle working directory would be used.
delete — Delete this puzzle working directory. Purely local--there is no server-side counterpart to delete (a puzzle already exists on the server before you can solve it, and isn't yours to remove); this only ever removes your own local files. Destructive--prompts for confirmation unless --force is given; requires --force outright if stdin/stdout aren't a terminal.

`cg puzzle import`¶

Build a fresh puzzle working directory: resolve PUZZLE to a real puzzle (in order of preference: a numeric puzzle ID; an exact pretty ID, e.g. 'literary-alfabet-soupe'; an exact-matching title; a case-insensitive-matching title), then resolve this codingamer's test session for it (Puzzle/generateSessionFromPuzzlePrettyId), then fetch its current state (TestSession/startTestSession). Imports the codingamer's existing saved answer if there is one, in whatever language it was written in; otherwise seeds a placeholder solution.src in --language. Unlike cg contribution import, uses the normal --puzzle-dir resolution (with a cwd/./puzzle fallback) rather than requiring an explicit new-directory argument--puzzle working directories are expected to be reused across different puzzles over time, one at a time.

usage: cg puzzle import [-h] [--language LANGUAGE] DIRECTORY PUZZLE

Arguments

DIRECTORY — Directory to build the working directory in. Required and always first, matching cg contribution import/create. Becomes the active puzzle directory (see cg puzzle activate).
PUZZLE — A puzzle reference: numeric puzzle ID, pretty ID (displayed title, lowercased with spaces replaced by hyphens, e.g. 'literary-alfabet-soupe'), exact title, or case-insensitive title--tried in that order until one resolves to a real puzzle.

Options

-l, --language LANGUAGE — Language to start in, e.g. 'C++'. Restores your most recent saved code for that language, or writes a placeholder if you've never used it here. Omit to use whichever language you last used for this puzzle (or Python3 if you've never attempted it at all).

`cg puzzle repair`¶

Reconstruct .meta/ (gitignored server-derived cache: the test session handle, plus read-only statement.html/stub_generator.cgstub reference copies) from puzzle.json's stable puzzle_id--for recovering after a fresh clone into a different repo (.meta/ is gitignored on purpose) or manual deletion/corruption of .meta/. Never touches data/.

usage: cg puzzle repair [-h]

`cg puzzle submit`¶

Submit the current local solution.src to the server for credit (TestSession/submit)--a real, permanent graded submission, unlike cg puzzle play-server. Note cg puzzle play-server also durably updates the server's copy of the code as a side effect of running a test case--this command is the one that actually grades it.

usage: cg puzzle submit [-h]

`cg puzzle play-server`¶

Run the current local solution.src against one or more of the puzzle's test cases via the server (TestSession/play--the IDE's "Test" button, not a real submission; see cg puzzle play for the entirely-local, no-network equivalent). With no TEST-INDEX arguments, runs every downloaded test case (.meta/tests/); give one or more 1-based indices to run just those. Exits 1 if any run errored or didn't match the expected output. Output matches cg puzzle play's format. Captured stdout is only printed for a failing test, unless --show-stdout is given.

usage: cg puzzle play-server [-h] [--show-stdout] [TEST-INDEX ...]

Arguments

[TEST-INDEX ...] — 1-based test case index/indices to run against (see CgTestSessionTestCase.index). With none given, runs every downloaded test case (.meta/tests/).

Options

--show-stdout — Print captured stdout even for a passing test. Always printed for a failing/errored test regardless.

`cg puzzle play`¶

Run the current local solution.src against the downloaded .meta/tests/ test cases entirely locally (no network access at all)--by shelling out to the appropriate interpreter as a subprocess, comparing captured stdout to each test's expected output (see cg puzzle play-server for the real, server-side equivalent). Currently only Python3 solutions are supported. With no TEST-INDEX arguments, runs every downloaded test case; give one or more 1-based indices to run just those. Exits non-zero if any test case fails. Captured stdout is only printed for a failing test (as part of its diff), unless --show-stdout is given.

usage: cg puzzle play [-h] [--show-stdout] [--timeout SECONDS] [--build-timeout SECONDS]
                      [TEST-INDEX ...]

Arguments

[TEST-INDEX ...] — 1-based downloaded test case index/indices to run (see .meta/tests//). With none given, runs every downloaded test case.

Options

--show-stdout — Print captured stdout even for a passing test. Always shown for a failing test (as part of its diff) regardless.
--timeout SECONDS (default: 10.0) — Per-test-case wall-clock timeout. Default 10.0.
--build-timeout SECONDS (default: 120.0) — Wall-clock timeout for the one-time build step that runs before any test case. Separate from --timeout, and far more generous, because a cold build can pull/build a container image and compile from scratch. Default 120.0. Ignored for languages that need no build (e.g. Python3).

`cg puzzle description`¶

Display the puzzle's problem statement, rendered from the cached .meta/statement.html (no network access--run cg puzzle import/repair first if missing). Section headers and the Example's input/output text are color-highlighted when writing to a real terminal. With --json (top-level option), prints the parsed [{kind, text}, ...] blocks instead.

usage: cg puzzle description [-h]

`cg puzzle diff`¶

Show a unified diff between the local solution.src and the server's current last-submitted answer for this puzzle.

usage: cg puzzle diff [-h]

`cg puzzle status`¶

Human-friendly summary of this puzzle: title, language, and local-edit status. By default entirely local (no network access); pass --refresh to also check for local edits against the server's last-submitted answer and fetch live progress/score (two live calls--there is no local cache for puzzles, unlike cg contribution status, so this is always genuinely live, every time). With --json (top-level option), renders as JSON instead of text.

usage: cg puzzle status [-h] [--refresh]

Options

--refresh — Also check for local edits against the server's last-submitted answer and fetch live progress/score (two live calls).

`cg puzzle discard-local`¶

Discard local edits: overwrite solution.src with the server's current last-submitted answer for this puzzle. Purely local--no network side effect beyond the read.

usage: cg puzzle discard-local [-h]

`cg puzzle debug`¶

Debug-session plumbing for languages whose debugger attaches to a running target (C++, via gdbserver in its container). Normally invoked for you by the VS Code tasks cg puzzle vscode generates, not typed by hand. Languages whose debugger launches the program itself--Python3--don't use these at all.

usage: cg puzzle debug [-h] COMMAND ...

Subcommands

start — Build the debug profile and start a stopped debug target fed by TEST-INDEX's input, ready for a debugger to attach. Prints the connection details.
stop — Stop a debug target started by cg puzzle debug start. Always succeeds, including when nothing is running--it's wired to a postDebugTask, which fires even for a session that never really began.

`cg puzzle debug start`¶

Build the debug profile and start a stopped debug target fed by TEST-INDEX's input, ready for a debugger to attach. Prints the connection details.

usage: cg puzzle debug start [-h] [--build-timeout SECONDS] TEST-INDEX

Arguments

TEST-INDEX — Downloaded test case index whose input.txt feeds the debugged run.

Options

--build-timeout SECONDS (default: 120.0) — Wall-clock timeout for the debug build.

`cg puzzle debug stop`¶

Stop a debug target started by cg puzzle debug start. Always succeeds, including when nothing is running--it's wired to a postDebugTask, which fires even for a session that never really began.

usage: cg puzzle debug stop [-h]

`cg puzzle build`¶

Compile data/solution.src, if its language needs compiling (a no-op for interpreted languages like Python3). Normally you don't need this--cg puzzle play builds first automatically--but it's useful to compile without running, or to warm a cold container image up front. Near-instant when the source hasn't changed since the last successful build. Compiler diagnostics go to stderr.

usage: cg puzzle build [-h] [--profile {run,debug}] [--build-timeout SECONDS]

Options

--profile {run,debug} (default: run) — Which build to produce. "debug" is built for debuggability rather than speed (no optimization, full symbols) and is what a debug session uses. Ignored by languages that need no build. Default: run.
--build-timeout SECONDS (default: 120.0) — Wall-clock timeout. Generous by default, because a cold build can pull and build a container image. Default 120.0.

`cg puzzle set-language`¶

Switch this puzzle to a different language, restoring your own most recent code for it. CodinGame keeps your latest source per language, so anything you'd previously written in the target language comes back; a language you've never used gets a placeholder. Refuses if data/solution.src holds work the server doesn't have (submit it first, or pass --force to discard it). Changes local state only--the server's current language follows once you run a server-side test or submit in the new one.

usage: cg puzzle set-language [-h] [--force] LANGUAGE

Arguments

LANGUAGE — CodinGame language ID to switch to, e.g. 'C++', 'Python3'.

Options

-f, --force — Switch even if data/solution.src has changes the server doesn't have, discarding them.

`cg puzzle activate`¶

Make DIRECTORY the active puzzle working directory, so subsequent cg puzzle commands use it without needing --puzzle-dir. Set automatically by cg puzzle import, so this is for switching between working directories you already have. Outranks the configured default (cg settings set puzzle-dir); cg puzzle deactivate clears it.

usage: cg puzzle activate [-h] [DIRECTORY]

Arguments

[DIRECTORY] (default: /home/runner/work/codingame-tools/codingame-tools) — The puzzle working directory to activate. Defaults to the current directory, so cd into one and run this with no arguments.

`cg puzzle deactivate`¶

Clear the active puzzle working directory, so cg puzzle commands fall back to the configured default and the usual directory discovery. Does not touch any files--only the selection.

usage: cg puzzle deactivate [-h]

`cg puzzle select-test`¶

Choose which test case cg puzzle debug (and cg play --selected) runs against. Debugging feeds one stdin, so it needs exactly one test. Recorded in .meta/selected-test.json rather than in launch.json, which is what lets one VS Code debug configuration serve every puzzle directory instead of being regenerated per directory. With no INDEX, shows the current selection.

usage: cg puzzle select-test [-h] [--clear] [INDEX]

Arguments

[INDEX] — 1-based test case index, as shown by cg puzzle play. Omit to show the current selection.

Options

--clear — Forget the explicit selection and fall back to the first test case.

`cg puzzle where`¶

Show which puzzle working directory would be used.

usage: cg puzzle where [-h]

`cg puzzle delete`¶

Delete this puzzle working directory. Purely local--there is no server-side counterpart to delete (a puzzle already exists on the server before you can solve it, and isn't yours to remove); this only ever removes your own local files. Destructive--prompts for confirmation unless --force is given; requires --force outright if stdin/stdout aren't a terminal.

usage: cg puzzle delete [-h] [--force]

Options

-f, --force — Skip the interactive confirmation prompt. Required if stdin/stdout aren't a terminal.

Generated from the parser itself. For when to use these, see the CLI guides.

cg puzzle¶

cg puzzle¶

cg puzzle import¶

cg puzzle repair¶

cg puzzle submit¶

cg puzzle play-server¶

cg puzzle play¶

cg puzzle description¶

cg puzzle diff¶

cg puzzle status¶

cg puzzle discard-local¶

cg puzzle debug¶

cg puzzle debug start¶

cg puzzle debug stop¶

cg puzzle build¶

cg puzzle set-language¶

cg puzzle activate¶

cg puzzle deactivate¶

cg puzzle select-test¶

cg puzzle where¶

cg puzzle delete¶

`cg puzzle`¶

`cg puzzle import`¶

`cg puzzle repair`¶

`cg puzzle submit`¶

`cg puzzle play-server`¶

`cg puzzle play`¶

`cg puzzle description`¶

`cg puzzle diff`¶

`cg puzzle status`¶

`cg puzzle discard-local`¶

`cg puzzle debug`¶

`cg puzzle debug start`¶

`cg puzzle debug stop`¶

`cg puzzle build`¶

`cg puzzle set-language`¶

`cg puzzle activate`¶

`cg puzzle deactivate`¶

`cg puzzle select-test`¶

`cg puzzle where`¶

`cg puzzle delete`¶