coderpad-cli
Manage starter code, create Interview pads, and inspect available environments using coderpad-py. This independent CLI preserves titles, descriptions, and other metadata by updating only the supplied starter-code field.
Requires Python 3.12 or later. Install with uv tool install coderpad-cli or pip install coderpad-cli.
To run a checkout:
uv sync --locked
uv run coderpad --help
uv run python -m coderpad_cli --version
Usage
Use synthetic question ID 123456 below in place of your own question ID. Exactly one content source is required:
coderpad questions upload 123456 --directory ./starter --dry-run
coderpad questions upload 123456 --directory ./starter --exclude '*.zip'
coderpad questions upload 123456 --file ./starter.py
Real uploads read CODERPAD_API_KEY from the environment. Get a key from your CoderPad dashboard settings. Missing, empty, and whitespace-only keys fail clearly. Dry runs need no key and make no network requests.
Single files must be UTF-8. Their text is preserved exactly, including CRLF, blank lines, trailing whitespace, a UTF-8 BOM, and documentation markers. Empty files are valid. Neither paths nor IDs are inferred from repository configuration. Inputs are fully read or staged before a mutation is issued. Errors exit nonzero. API error response bodies and credentials are never printed. Uploads retain the SDK’s retry behavior.
Inspecting resources
Read a complete question as JSON, including multi-file starter overlays, hidden/deleted flags, and project-template metadata:
coderpad questions get 123456
coderpad user get
coderpad languages list
coderpad languages get multifile_python
These commands use CODERPAD_API_KEY. The user response contains the key owner’s name, anonymous identifier, and pad-creation capability. CoderPad does not return the owner’s email or organization role. Question files describe changes to a project template, so unchanged template files may be omitted. The question’s variant summaries identify templates, while questions variants get retrieves a variant’s code.
Inspect Screen campaigns with the separate CODERPAD_SCREEN_API_KEY:
coderpad screen campaigns list
coderpad screen campaigns get 121 --region eu
For EU accounts, use --region eu instead of the default us region. Only the Screen key is required for these commands. A campaign definition contains its ordered question selections, settings, and team identity. These read commands print only the requested JSON resource to standard output and do not change remote resources.
Question variants
Create a variant once, using a language or project-template slug:
coderpad questions variants create 123456 --language python3 --dry-run
coderpad questions variants create 123456 --language python3 > variant.json
coderpad questions variants create 123456 --language javascript --file ./starter.js
coderpad questions variants create 123456 --language multifile_python --directory ./starter --exclude '*.zip'
Successful creation writes only JSON to standard output, such as {"question_id": 123456, "variant_id": 7}. Save the returned ID in your upload configuration for later updates, because the CLI does not save IDs or match existing variants by language or title. Every real invocation creates a new variant and is never automatically retried. Existing question metadata and other variants are not changed.
Omitting both sources uses the language or project template’s default content. Use --file for single-file starter code; an empty file explicitly creates blank code instead of using the default. Use --directory for project files, which are layered over the template at creation rather than replacing all template files. Source selection and UTF-8 validation match variant uploads. --file and --directory are mutually exclusive. --exclude requires a directory. CoderPad validates whether the supplied language or template is available. Dry runs validate local inputs and print a JSON plan with the operation, question ID, language, and selected files, but no invented variant ID. They require neither credentials nor network access. Errors go to standard error with a nonzero exit status. If a creation response is lost or invalid, check the question before retrying to avoid creating a duplicate.
To update an existing variant rather than the question’s starter code, add --variant-id:
coderpad questions upload 123456 --variant-id 7 --directory ./starter --exclude '*.zip' --dry-run
coderpad questions upload 123456 --variant-id 7 --directory ./starter --exclude '*.zip'
coderpad questions upload 123456 --variant-id 8 --file ./starter.py
Question and variant IDs must be positive decimal integers. The variant must already exist. Only its starter code changes; the question metadata, other variants, selected language or project template, and solution are preserved. Directory uploads replace the variant’s files using the SDK’s JSON API. Every selected file must be UTF-8, including during a dry run. Exclude binary assets explicitly or use a normal question upload, which continues to support binary files through the SDK’s ZIP importer. File text is preserved exactly for both variant upload modes. Dry runs identify the variant and selected files without requiring a key or making a request.
Directory selection
Both Git and non-Git directories work. Paths are relative to the current working directory. A Git worktree’s .git file also identifies its root.
In a Git repository, rules are inherited from the nearest Git root down to the upload directory. Outside Git, rules start at the upload directory; unrelated parent .gitignore files are not used.
Each traversed directory adds its own .gitignore rules. Later matching rules override earlier ones, and deeper files override ancestor rules. Patterns are relative to their owning directory. Directory-only rules and negations follow Gitignore semantics. Excluded directories are pruned, so a child cannot re-include itself unless its parent is re-included first. This also applies to ancestors of an explicitly selected nested upload root.
Ignore rules apply to tracked files too. Global Git excludes and .git/info/exclude are not read. Hidden files, including .gitignore, are uploaded unless excluded.
.git files and directories are always excluded at every depth. Repeatable --exclude PATTERN options form a final Gitignore rule layer, relative to the upload root. This layer can exclude files re-included by .gitignore; its own later negations can undo its earlier patterns. It cannot re-include a file excluded by .gitignore or Git metadata.
ZIP files are included by default. Use --exclude '*.zip' to omit them. Add other exclusions explicitly, such as --exclude node_modules/.
Selected symlinks (including directory, broken, and external links) and symlinks in the source path are rejected rather than dereferenced. Ignored links are skipped. Symlinked .gitignore files are rejected when their rules would be read. Special files are rejected. Empty selections fail. File bytes are copied to a temporary directory, and the SDK independently validates and serializes that directory using its ZIP importer for normal question uploads. Variant uploads send the staged files as UTF-8 JSON content instead.
Development and distribution
Development checks, release setup, and build instructions for Docker, Nix, and standalone binaries are in docs/source/development.rst. The generated CLI reference is in docs/source/cli.rst. There are no prebuilt artifacts yet.
See docs/source/migration.rst for migrating an existing shell uploader and keeping repository-specific snippet preparation outside this CLI.
Creating pads
Inspect an environment before creating a project pad:
coderpad languages get multifile_python
coderpad pads create --language multifile_python --dry-run
coderpad pads create --language multifile_python --directory ./starter
coderpad pads create --language python3 --file ./starter.py
coderpad pads create --question-id 123456
Directory uploads use the SDK’s ZIP importer and the same Git ignore and exclusion handling as question uploads. Omit starter code to use the environment’s default files. Real creation consumes your account’s pad quota. Dry runs need no API key and make no network requests.
Metadata
Release files for coderpad-cli 2026.11.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| coderpad_cli-2026.11.11.tar.gz | 267.7 kB | With provenance | Details for coderpad_cli-2026.11.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| coderpad_cli-2026.11.11-py3-none-any.whl | Python 3 | none | any | Details for coderpad_cli-2026.11.11-py3-none-any.whl |
Total release size: 288.0 kB
Release files / coderpad_cli-2026.11.11.tar.gz
| Download URL | coderpad_cli-2026.11.11.tar.gz |
|---|---|
| Size | 267.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
151fb74faa8aeb2401865045c93bee09a7b4064db7164caf211f783817f5e7a4
|
|
BLAKE2b-256 checksum How to use checksums |
730a0b4e3351d1acf31b12a42eca1bc2bf4c2eb91d8133c444f7611360b72d6e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / coderpad_cli-2026.11.11-py3-none-any.whl
| Download URL | coderpad_cli-2026.11.11-py3-none-any.whl |
|---|---|
| Size | 20.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b47a63ca2d77095c15e54e98e264fcbc901731667a9fb7cc31f3e1e42731b471
|
|
BLAKE2b-256 checksum How to use checksums |
ce98c9edecc14079550d576239cfb5e4c2c8dab6064483a8b4a15f48e9baea8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for coderpad-cli 2026.11.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for coderpad_cli-2026.11.11.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.