CLI Documentation

Build, test, and submit solutions from your terminal

Installation

$ curl -fsSL https://codingchallenge.dev/install_cli.sh | bash

This downloads and installs the codingchallenge binary to your system.

Quick Start

Get from zero to submission in 5 steps:

1
Login
$ codingchallenge login
2
Navigate to your project and select a challenge
$ cd ~/my-project && codingchallenge challenge select
3
Build your solution
$ codingchallenge build
4
Run tests locally
$ codingchallenge test
5
Submit for grading
$ codingchallenge submit

Commands Reference

codingchallenge login

Authenticate with the platform by opening a browser window. Supports email/password, GitHub, Google, and Discord. Tokens are stored locally.

$ codingchallenge login

Credentials are saved to ~/.codingchallenge/tokens.json and refreshed automatically.

codingchallenge logout

Clear stored credentials from your machine.

$ codingchallenge logout

codingchallenge challenge select

Interactively pick one of your started challenges. Downloads Dockerfile, docker-compose.yml, and test scripts to the .codingchallenge/ directory.

$ codingchallenge challenge select

Creates a .codingchallenge.yaml config file in your project root with challenge and language metadata.

codingchallenge build

Build your solution using Docker Compose. Equivalent to running docker compose build app.

$ codingchallenge build

Streams build output directly to your terminal. Make sure Docker is running before executing this command.

codingchallenge test

Build your app and run the K6 test suite for your current level. Results are displayed in a formatted table.

$ codingchallenge test

Options

--localSkip Docker build and test against your locally running app
--port <number>Port your app is running on (default: 8080, used with --local)

Example: test against a locally running app for faster iteration:

$ codingchallenge test --local --port 8080

codingchallenge submit

Build your solution, zip the source code (excluding .codingchallenge/, .git/, node_modules/, bin/, obj/, etc.), upload it to the platform, and poll for grading results.

$ codingchallenge submit

Options

--skip-buildSkip the Docker build step if you already built successfully
$ codingchallenge submit --skip-build

codingchallenge update

Check for a new CLI version and automatically download and install it if one is available.

$ codingchallenge update

The CLI also checks for updates in the background once per hour. If a newer version is available, a reminder banner is shown at the start of every command until you update.

codingchallenge help

Display all available commands, configuration options, and environment variables.

$ codingchallenge help

Configuration

Global Config

Location: ~/.codingchallenge/config.json

backendUrlAPI server URL
webAppUrlWeb application URL
supabaseUrlAuthentication server URL

Project Config

Location: .codingchallenge.yaml (in project root, auto-generated by challenge select)

Contains challenge ID, name, selected language, and current level. You should not need to edit this file manually.

Environment Variables

Override config values with environment variables:

BACKEND_URLOverrides backendUrl
WEB_APP_URLOverrides webAppUrl
SUPABASE_URLOverrides supabaseUrl

Capabilities

Some challenges and levels need a backing service such as a database or cache. The platform attaches the required service as a sidecar to the tester pod (and to the local docker-compose) and injects a connection string into your app via an environment variable. Capabilities accumulate across levels: once a capability unlocks at level N, it stays available at every level > N.

Supported capabilities

CapabilityEnv varPortImage
PostgreSQLDATABASE_URL5432postgres:16-alpine
RedisREDIS_URL6379redis:7-alpine

Each container runs with its own CPU/memory/ephemeral-storage limits. State is destroyed between submissions; do not rely on data persisting across runs.

Reading the connection string in your app

var conn = Environment.GetEnvironmentVariable("DATABASE_URL");
if (!string.IsNullOrEmpty(conn))
{
    // open with Npgsql / EF, retrying on connect failure
    // (postgres can take a few seconds to accept connections at startup)
}

Local development

Running codingchallenge test brings up the capability sidecars automatically through docker-compose; your app reads the connection strings from its environment without any extra setup.

In --local mode the CLI starts only the sidecars and lets you run your app on the host. Print the connection strings with:

$ codingchallenge env

Or pipe them straight into your shell:

$ eval $(codingchallenge env)

Troubleshooting

App is unhealthy

Make sure your application listens on port 8080 inside the Docker container. Check your Dockerfile EXPOSE directive and application configuration.

No test results found

Check the Docker build output for errors. Your app may have failed to compile or start. Run codingchallenge build first to verify.

Not logged in

Run codingchallenge login to authenticate. Your tokens may have expired.

No started challenges found

You need to start a challenge and select a programming language on the web app first, then use codingchallenge challenge select.

Docker not running

Make sure Docker Desktop (or Docker Engine) is running. The CLI uses Docker Compose v2 to build and test your solution.

Tips

Use test --local for fast iteration during development. No Docker rebuild needed.

Always run test before submit to avoid burning submissions on build failures.

The submit command automatically excludes .codingchallenge/, .git/, node_modules/, bin/, obj/, target/, and other common build artifact directories from the upload.

If your build is already up-to-date, use submit --skip-build to save time.

Performance tests may show different results locally vs. on the grading server. Focus on correctness first, then optimize.

Keep the CLI up to date with codingchallenge update to get the latest features and bug fixes. The CLI will remind you automatically when a new version is available.