# CLI reference ``` curl -fsSL https://cthree.cloud/install.sh | sh # install (Linux, macOS) c3 update # update to the latest release c3 version ``` `c3 docs` prints every page of this site as plain text, for piping into an agent or a file. ## Jobs[​](#jobs "Direct link to Jobs") ### c3 deploy[​](#c3-deploy "Direct link to c3 deploy") Submit a job from the `.c3` in the current folder or any parent. ``` c3 deploy [script] [-f] [-v] [-p ] [--json] [--dry-run] [--list-files] [--storage legacy|verified] ``` | Flag | Effect | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `--storage legacy\|verified` | Storage pathway; defaults to legacy. Verified requires compatible job execution and fails before upload when unavailable. | | `-f`, `--follow` | Stream logs until the job finishes | | `-v`, `--verbose` | With `-f`, include system and agent log streams | | `-p`, `--provider ` | Pin a provider for this run | | `--json` | Print the submitted job as one JSON object. Not with `-f` | | `--dry-run` | Show the route, rate and availability. Nothing is uploaded | | `--list-files` | Print the files that would be uploaded and exit. No sign-in needed | | `[script]` | A legacy `.sbatch` script instead of `.c3` | Plain `c3 deploy` and `c3 deploy --storage=legacy` use the existing storage and execution path. `c3 deploy --storage=verified` uses private source/origin storage and the ingestion publisher, and requires verified job execution to be enabled. There is no automatic fallback between them. The option applies both to `.c3` projects and script arguments. Standalone `c3 data` uploads can exercise verified storage independently of job execution. For legacy script submissions (`c3 deploy job.sbatch`), the CLI looks for a project `.c3` from the workspace folder upward, skipping directories named `.c3`, such as the credential store at `~/.c3`. If none exists, it writes a generated project name. If it cannot read the project name from the workspace's own `.c3`, it moves that file to `.c3.broken-` and writes a starter config with a new generated project name, `script: run.sh`, `hardware: l40`, `time: "01:00:00"`, and `output: [./results]`. It also sets `python.project: ./` when both `pyproject.toml` and `uv.lock` exist. The flight plan reports the replacement and backup filename; inspect the backup to recover custom settings. An unreadable parent config remains an error and is not replaced. Config-based `c3 deploy` (without a script argument) still reports config-loading errors. ### c3 squeue[​](#c3-squeue "Direct link to c3 squeue") ``` c3 squeue [-n ] [--json] c3 squeue [--json] ``` Lists every active job plus the most recent finished ones (`-n`, default 10). With a job ID, shows one job in full: route, latest attempt and failure diagnosis. ### c3 logs[​](#c3-logs "Direct link to c3 logs") ``` c3 logs [-f] [-v] ``` Prints setup progress and your script's stdout and stderr. `-f` tails until the job ends. ### c3 cancel[​](#c3-cancel "Direct link to c3 cancel") ``` c3 cancel ``` Stops a pending or running job. Time already used is billed. ### c3 pull[​](#c3-pull "Direct link to c3 pull") ``` c3 pull [job-id] [folder] [--json] c3 pull --all [--json] ``` Downloads a job's artifacts into `.//`. With no ID, downloads previously undownloaded jobs among the latest 100 succeeded jobs. `folder` limits the download to one artifact directory. ### c3 init[​](#c3-init "Direct link to c3 init") Writes a starter `.c3` in the current folder. ### c3 migrate[​](#c3-migrate "Direct link to c3 migrate") ``` c3 migrate job.sbatch ``` Converts a Slurm script's `#SBATCH` directives into a `.c3`. ## Data[​](#data "Direct link to Data") ``` c3 data ls [-l] [-R] # datasets, versions or files c3 data cp # upload or download; local paths one side, /datasets or /jobs the other c3 data rm [-r] [-f] [-n] # delete a version, or a dataset with -r; -n is a dry run c3 data du [--dedup] # storage used c3 data log [-n ] # version history ``` Path forms: `/datasets//`, `/datasets//@/`, `/datasets//@latest/`, `/jobs//`, `/projects//jobs/`. See [Datasets](https://docs.cthree.cloud/datasets.md). ## Hardware[​](#hardware "Direct link to Hardware") ``` c3 list [--all] [--class ] [--provider ] [--json] ``` Shows classes, profiles, providers, prices and availability. `-al` is short for `--all`. See [Hardware and capacity](https://docs.cthree.cloud/hardware.md). ## Account[​](#account "Direct link to Account") ``` c3 login # sign in through the browser; credentials stored in ~/.c3/ c3 logout c3 whoami [--json] # user, email, verification status, organisation c3 verify-email # resend the verification email c3 apikey create c3 apikey list c3 apikey revoke ``` See [Authentication and API keys](https://docs.cthree.cloud/authentication.md). ## Billing[​](#billing "Direct link to Billing") ``` c3 balance # credit, plan and storage usage c3 topup [amount] # add credit, whole pounds, £10 to £10,000; opens checkout c3 upgrade [tier] [-y] # free, pro or team; -y skips confirmation for scripts ``` See [Pricing and plans](https://docs.cthree.cloud/pricing.md). ## Environment variables[​](#environment-variables "Direct link to Environment variables") | Variable | Effect | | ----------------- | -------------------------------------------------- | | `C3_API_KEY` | Authenticate with an API key instead of `c3 login` | | `C3_AUTH_TOKEN` | Raw bearer token, for CI | | `C3_PROVIDER` | Default provider pin, same as `-p` | | `C3_API_ENDPOINT` | Control plane URL. Leave unset for production | ## JSON output[​](#json-output "Direct link to JSON output") `--json` on `deploy`, `squeue`, `pull`, `list` and `whoami` prints one JSON document to stdout and sends progress and warnings to stderr. Field tables for `deploy` and `squeue` are on [Project configuration](https://docs.cthree.cloud/configuration.md#machine-readable-output).