Reference
CLI reference
Every command, argument and flag, plus global flags, environment variables and exit codes.
Overview
The executable is clockingcloud. Commands follow clockingcloud <command> [subcommand] [arguments] [flags]. Flags can appear before or after positional arguments. Boolean flags take no value. Repeatable flags can be given more than once.
This page is generated from the same machine-readable specification that is published at /docs/cli.json, which is used to build shell completions and the man page.
Global flags
These flags are accepted by every command.
| Flag | Default | Description |
|---|---|---|
| -o, --output <table|json|yaml> | table | Output format. Use json in scripts. Errors are always written to stderr. |
| -q, --quiet | Print only identifiers (names, URLs, request IDs). Useful with shell substitution. | |
| -y, --yes | Answer yes to confirmation prompts. Required for destructive commands when stdin is not a terminal. | |
| --api-url <url> | https://www.clockingcloud.com | Override the API base URL. Also settable with CLOCKINGCLOUD_API_URL. |
| --no-color | Disable ANSI colors. Also honored through the NO_COLOR environment variable. | |
| --debug | Print HTTP request and response metadata to stderr. Credentials are redacted. | |
| -h, --help | Show help for the command. | |
| -v, --version | Print the CLI version and exit. |
Environment variables
| Variable | Description |
|---|---|
| CLOCKINGCLOUD_API_KEY | API key used instead of the stored login. Takes precedence over clockingcloud login. |
| CLOCKINGCLOUD_API_URL | API base URL. Defaults to https://www.clockingcloud.com. |
| CLOCKINGCLOUD_CONFIG_DIR | Configuration directory. Defaults to $XDG_CONFIG_HOME/clockingcloud, or ~/.config/clockingcloud. |
| CLOCKINGCLOUD_OUTPUT | Default output format (table, json or yaml). |
| CLOCKINGCLOUD_NO_UPDATE_CHECK | Set to 1 to disable the once-a-day check for a newer CLI version. |
| NO_COLOR | Set to any value to disable colored output. |
| HTTPS_PROXY / NO_PROXY | Standard proxy variables. The CLI honors them for every request. |
Exit codes
Scripts and CI should branch on the exit code rather than parsing output.
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Unexpected error. Re-run with --debug and include the request ID when contacting support. |
| 2 | Invalid usage: unknown flag, missing argument or invalid clockingcloud.yaml. |
| 3 | Not authenticated, or the API key was rejected. |
| 4 | Insufficient credits to start or continue the operation. |
| 5 | The named resource was not found. |
| 6 | Conflict: the resource already exists or is in a state that blocks the operation. |
| 7 | Timed out while waiting (see --timeout). |
| 130 | Interrupted by the user (Ctrl+C). Running generations keep going unless --cancel-on-exit is set. |
Commands
Account
clockingcloud login
Sign in to your ClockingCloud account.
Opens your browser to authorize this machine and stores a credential in the configuration directory. Use --device on a machine without a browser, or --with-api-key to read an API key from stdin.
clockingcloud login [--device] [--no-browser] [--with-api-key]Flags
| Flag | Default | Description |
|---|---|---|
| --device | Use the device-code flow. Prints a short code and a URL to open on any other device. | |
| --no-browser | Print the authorization URL instead of opening a browser. | |
| --with-api-key | Read an API key from stdin and store it. For CI and servers. |
clockingcloud login
clockingcloud login --device
echo "$CLOCKINGCLOUD_API_KEY" | clockingcloud login --with-api-keyclockingcloud logout
Remove stored credentials from this machine.
Deletes the local credential and revokes the CLI session. API keys are not revoked; use clockingcloud api-key rm for that.
clockingcloud logoutclockingcloud logoutclockingcloud whoami
Show the signed-in account and credit balance.
clockingcloud whoamiclockingcloud whoami
clockingcloud whoami -o jsonclockingcloud api-key create
Create an API key for CI/CD and the REST API.
The secret is printed once and never shown again. Store it in your secret manager immediately.
clockingcloud api-key create --name <name> [--expires <duration>]Flags
| Flag | Default | Description |
|---|---|---|
| --name <string>required | A label to identify the key (up to 60 characters). | |
| --expires <duration> | never | Expire the key after a duration such as 30d or 12h. |
clockingcloud api-key create --name github-actions --expires 90dclockingcloud api-key ls
List API keys (prefix, name, created, last used, expiry).
clockingcloud api-key lsclockingcloud api-key lsclockingcloud api-key rm
Revoke an API key immediately.
clockingcloud api-key rm <id>Arguments
<id>Key ID from clockingcloud api-key ls.
clockingcloud api-key rm key_8f3a1cRun
clockingcloud run
Run a model once and download the result.
Starts a short-lived instance, runs the generation, writes the files to --out, and releases the GPU. You are billed per second of GPU time from when the model is loaded until the result is written. Use deploy for repeated traffic.
clockingcloud run <model> --prompt <text> [flags]Arguments
<model>A model ID from clockingcloud models ls, or hf://org/model.
Flags
| Flag | Default | Description |
|---|---|---|
| -p, --prompt <text>required | The text prompt. | |
| --negative-prompt <text> | Concepts to steer away from. Ignored by models that do not support it. | |
| --image <path|url> | Input image for editing and image-to-video models (qwen-image-edit, wan-2.2-i2v). | |
| --width <px> | 1024 | Image width. Must be a multiple of 16. |
| --height <px> | 1024 | Image height. Must be a multiple of 16. |
| --seconds <n> | 5 | Video length in seconds. Video models only. |
| --fps <n> | model default | Video frames per second. Video models only. |
| --steps <n> | model default | Number of denoising steps. |
| --guidance <n> | model default | Guidance scale. |
| --seed <n> | random | Seed for reproducible output. |
| --n <count> | 1 | Number of outputs to generate in one batch (1 to 16). |
| --gpu <auto|l40s|h100|h200|b200> | auto | GPU type. auto picks the smallest GPU that fits the model. |
| -O, --out <dir> | . | Directory for the output files. |
| --no-wait | Return a request ID immediately instead of waiting for the result. | |
| --timeout <duration> | 30m | Give up waiting after this long. The generation is not cancelled. |
| --cancel-on-exit | Cancel the generation if the command is interrupted. |
clockingcloud run z-image-turbo --prompt "a ceramic mug on a linen table, soft light" --out ./shots
clockingcloud run wan-2.2 --prompt "waves at dusk" --seconds 5 --gpu h200
clockingcloud run qwen-image-edit --image ./mug.png --prompt "make the mug emerald green"clockingcloud dev
Debug your setup in a CPU sandbox with the same image.
Runs the setup steps and a shell in a CPU-only sandbox built from the same image your instance will use. No GPU is attached, so debugging costs only CPU time. Press Ctrl+D to exit and tear the sandbox down.
clockingcloud dev [-f <file>] [--shell <shell>]Flags
| Flag | Default | Description |
|---|---|---|
| -f, --file <path> | clockingcloud.yaml | Configuration file. |
| --shell <string> | bash | Shell to start in the sandbox. |
clockingcloud dev
clockingcloud dev -f configs/prod.yamlclockingcloud plan
Validate clockingcloud.yaml and show the GPU and estimated cost.
Parses and validates the file, resolves gpu: auto, checks that volumes and secrets exist, and prints an estimate. Nothing is created and nothing is billed. Exits with code 2 if the file is invalid.
clockingcloud plan [-f <file>] [--gpu <type>] [--hours <n>]Flags
| Flag | Default | Description |
|---|---|---|
| -f, --file <path> | clockingcloud.yaml | Configuration file. |
| --gpu <type> | Override the GPU for the estimate. | |
| --hours <n> | 1 | Hours of active GPU time to price. |
clockingcloud plan
clockingcloud plan -f clockingcloud.yaml --gpu h100 --hours 8Instances
clockingcloud deploy
Create or update an instance. It starts on demand and scales to zero.
Creates the instance if the name is new, or updates it in place. With scale.min of 0 (the default) no GPU runs until the first request arrives; with scale.min of 1 or more the instance starts immediately. Re-running with the same input is safe.
clockingcloud deploy [<model|path>] [-f <file>] [flags]Arguments
[target]A model ID, hf://org/model, or a local directory. Omit when using -f.
Flags
| Flag | Default | Description |
|---|---|---|
| -f, --file <path> | Read the instance definition from a clockingcloud.yaml file. | |
| --name <name> | Instance name. Defaults to the model ID or directory name. | |
| --gpu <auto|l40s|h100|h200|b200> | auto | GPU type. |
| --gpus <n> | 1 | GPUs per replica (1, 2, 4 or 8). |
| --min <n> | 0 | Minimum replicas. 0 scales to zero. |
| --max <n> | 1 | Maximum replicas. |
| --idle-timeout <duration> | 60s | Stop a replica after this long without work. |
| --volume <name:/path[:ro]> | Mount a volume. Repeatable. | |
| -e, --env <KEY=value> | Set an environment variable. Repeatable. | |
| --no-wait | Return as soon as the definition is saved. | |
| --timeout <duration> | 15m | How long to wait for the instance to become ready. |
clockingcloud deploy z-image-turbo --name img-prod --max 8
clockingcloud deploy -f clockingcloud.yaml
clockingcloud deploy hf://org/custom-model --gpu h100 --volume weights:/models:roclockingcloud up
Provision and start an instance from clockingcloud.yaml right now.
Like deploy -f, but always starts a replica immediately, even when scale.min is 0. With --debug it picks the smallest compatible GPU, streams setup output, and stops the instance when you exit so a broken setup cannot keep billing.
clockingcloud up -f <file> [--gpu <type>] [--debug]Flags
| Flag | Default | Description |
|---|---|---|
| -f, --file <path> | clockingcloud.yaml | Configuration file. |
| --gpu <type> | Override the GPU in the file. | |
| --debug | Cheapest compatible GPU, streamed setup logs, automatic stop on exit. | |
| --timeout <duration> | 15m | How long to wait for the instance to become ready. |
clockingcloud up -f clockingcloud.yaml
clockingcloud up -f clockingcloud.yaml --gpu l40s --debugclockingcloud ls
List instances with state, GPU, replicas and uptime.
clockingcloud ls [--state <state>]Flags
| Flag | Default | Description |
|---|---|---|
| --state <state> | Filter by provisioning, running, scaling, stopping, stopped or failed. |
clockingcloud ls
clockingcloud ls --state running -o jsonclockingcloud status
Show details for one instance.
clockingcloud status <name>Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
clockingcloud status img-prodclockingcloud start
Start a stopped instance.
clockingcloud start <name> [--no-wait]Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
Flags
| Flag | Default | Description |
|---|---|---|
| --no-wait | Return without waiting for ready. |
clockingcloud start img-prodclockingcloud stop
Stop an instance and release its GPUs.
Billing for GPU time stops as soon as the GPUs are released. The definition and attached volumes are kept.
clockingcloud stop <name>Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
clockingcloud stop img-prodclockingcloud scale
Change minimum or maximum replicas without redeploying.
clockingcloud scale <name> [--min <n>] [--max <n>]Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
Flags
| Flag | Default | Description |
|---|---|---|
| --min <n> | Minimum replicas. | |
| --max <n> | Maximum replicas. |
clockingcloud scale img-prod --max 16
clockingcloud scale img-prod --min 0clockingcloud rm
Delete an instance definition.
Stops the instance first if it is running. Volumes are not deleted.
clockingcloud rm <name> [--yes]Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
clockingcloud rm img-prod --yesclockingcloud ssh
Open a shell on a running instance, or run one command.
Uses the SSH keys you added to your account. Without an argument after -- you get an interactive shell.
clockingcloud ssh <name> [-i <identity>] [-- <command>]Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
Flags
| Flag | Default | Description |
|---|---|---|
| -i, --identity <path> | Private key to use. Defaults to your SSH agent. | |
| --replica <n> | 0 | Replica index when the instance runs more than one. |
clockingcloud ssh img-prod
clockingcloud ssh img-prod -- nvidia-smiclockingcloud cp
Copy files to or from an instance.
Use <instance>:<path> for the remote side. Over SSH; requires a key.
clockingcloud cp [-r] <source> <destination>Arguments
<source>Local path or <instance>:<path>.<destination>Local path or <instance>:<path>.
Flags
| Flag | Default | Description |
|---|---|---|
| -r, --recursive | Copy directories. |
clockingcloud cp ./scripts img-prod:/workspace -r
clockingcloud cp img-prod:/out/render.png .Models
clockingcloud models ls
List supported models, default GPUs and per-second prices.
clockingcloud models ls [--kind image|video] [--prices]Flags
| Flag | Default | Description |
|---|---|---|
| --kind <image|video> | Filter by output type. | |
| --prices | Include the per-second rate for the default GPU. |
clockingcloud models ls
clockingcloud models ls --kind video --pricesStorage
clockingcloud volume create
Create a ClockingCloud Global Volume.
clockingcloud volume create <name> --size <gb>Arguments
<name>2 to 39 lowercase letters, numbers or dashes.
Flags
| Flag | Default | Description |
|---|---|---|
| --size <gb>required | Whole number of gigabytes, 10 to 10000. A GB or GiB suffix is accepted. |
clockingcloud volume create renders --size 500clockingcloud volume connect
Alias: clockingcloud drive connect
Connect an existing S3, Azure Blob or Google Cloud Storage bucket.
Registers the bucket as a named volume. Credentials come from account secrets (see the Storage guide). Data stays in your bucket; ClockingCloud caches it next to the GPU.
clockingcloud volume connect <uri> [--name <name>] [--read-only]Arguments
<uri>s3://bucket[/prefix], azure://container[/prefix] or gs://bucket[/prefix].
Flags
| Flag | Default | Description |
|---|---|---|
| --name <name> | Volume name. Defaults to the bucket name. | |
| --read-only | Mount read-only so jobs cannot write back. | |
| --secret <NAME> | Use a specific account secret for credentials. Repeatable. |
clockingcloud volume connect s3://brand-assets --name assets --read-only
clockingcloud drive connect gs://studio-rendersclockingcloud volume ls
List volumes with provider, size or URI, and attachments.
clockingcloud volume lsclockingcloud volume lsclockingcloud volume rm
Remove a volume.
Deleting a Global Volume permanently deletes its data. Removing a connected bucket only removes the link; your bucket is untouched.
clockingcloud volume rm <name> [--yes]Arguments
<name>Volume name.
clockingcloud volume rm renders --yesAccess
clockingcloud ssh-key add
Add a public SSH key to your account.
Accepts ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256/384/521 and sk-ssh-ed25519@openssh.com keys. Private keys are never uploaded.
clockingcloud ssh-key add <path> --name <name>Arguments
<path>Path to a public key file, for example ~/.ssh/id_ed25519.pub.
Flags
| Flag | Default | Description |
|---|---|---|
| --name <string>required | A label (up to 60 characters). |
clockingcloud ssh-key add ~/.ssh/id_ed25519.pub --name laptopclockingcloud ssh-key ls
List SSH keys and their SHA256 fingerprints.
clockingcloud ssh-key lsclockingcloud ssh-key lsclockingcloud ssh-key rm
Remove an SSH key.
clockingcloud ssh-key rm <name|fingerprint>Arguments
<key>Key name or SHA256 fingerprint.
clockingcloud ssh-key rm laptopclockingcloud secrets set
Create or replace an account secret.
Secrets are injected into instances as environment variables and can be referenced in clockingcloud.yaml as ${secrets.NAME}. Values are write-only: they can never be read back.
clockingcloud secrets set <NAME> [--value <value>]Arguments
<NAME>Uppercase letters, numbers and underscores.
Flags
| Flag | Default | Description |
|---|---|---|
| --value <string> | The value. If omitted, the CLI reads it from stdin or prompts without echo. |
clockingcloud secrets set WEBHOOK_TOKEN
cat key.json | clockingcloud secrets set GOOGLE_APPLICATION_CREDENTIALS_JSONclockingcloud secrets ls
List secret names and when they were last updated.
clockingcloud secrets lsclockingcloud secrets lsclockingcloud secrets rm
Delete a secret.
clockingcloud secrets rm <NAME>Arguments
<NAME>Secret name.
clockingcloud secrets rm WEBHOOK_TOKENObservability
clockingcloud logs
Read instance logs: setup output, stdout, stderr and system events.
clockingcloud logs <name> [--follow] [--since <duration>] [--replica <n>]Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
Flags
| Flag | Default | Description |
|---|---|---|
| -f, --follow | Stream new lines until interrupted. | |
| --since <duration> | 1h | Show lines newer than this. |
| --replica <n> | Only one replica. | |
| --grep <pattern> | Only lines matching the pattern. |
clockingcloud logs img-prod --follow
clockingcloud logs img-prod --since 15m --grep errorclockingcloud top
Live view of GPU utilization, memory, queue depth and cost per second.
clockingcloud top [<name>]Arguments
[name]Limit to one instance.
clockingcloud top
clockingcloud top img-prodclockingcloud trace
Show where the time went for one request.
Breaks a request into queue, cold start, weight load, denoising steps, decode and write-back, with the GPU seconds and cost of each.
clockingcloud trace <request-id>Arguments
<request-id>Request ID printed by clockingcloud run, or returned by the API.
clockingcloud trace req_01JA7X9K2Mclockingcloud metrics
Query or export instance metrics.
clockingcloud metrics <name> [--since <duration>] [--export <format>]Arguments
<name>Instance name (2 to 39 lowercase letters, numbers or dashes).
Flags
| Flag | Default | Description |
|---|---|---|
| --since <duration> | 1h | Time window. |
| --export <prometheus|json|otlp> | Print in a machine format for your monitoring stack. |
clockingcloud metrics img-prod --since 24h
clockingcloud metrics img-prod --export prometheusBilling
clockingcloud balance
Show your remaining prepaid credit.
clockingcloud balanceclockingcloud balance
clockingcloud balance -qclockingcloud usage
Break down spend by instance, model and GPU type.
clockingcloud usage [--since <duration>] [--by instance|model|gpu]Flags
| Flag | Default | Description |
|---|---|---|
| --since <duration> | 30d | Time window. |
| --by <instance|model|gpu> | instance | Group results. |
clockingcloud usage --since 7d --by modelTools
clockingcloud doctor
Check your installation, credentials and connectivity.
Verifies the CLI version, config directory permissions, authentication, API reachability, and that clockingcloud resolves to ClockingCloud and not to the system C compiler. Exits non-zero if any check fails.
clockingcloud doctorclockingcloud doctorclockingcloud version
Print CLI version, commit and platform.
clockingcloud versionclockingcloud version
clockingcloud version -o jsonclockingcloud update
Check for a newer version and print how to upgrade.
The CLI never replaces itself. When installed with Homebrew it prints the brew upgrade command to run.
clockingcloud updateclockingcloud updateclockingcloud completion
Print a shell completion script.
clockingcloud completion <bash|zsh|fish>Arguments
<shell>bash, zsh or fish.
clockingcloud completion zsh > "${fpath[1]}/_clockingcloud"clockingcloud config
Read or change CLI settings.
Keys: output (table, json, yaml), api_url, update_check (true or false).
clockingcloud config <ls|get|set> [<key>] [<value>]clockingcloud config ls
clockingcloud config set output jsonSomething unclear or missing? Email hello@clockingcloud.com.