Command Line Interface¶

Use cscc-cli to authenticate, submit image builds, stream build logs, and manage your own API tokens.

Access: All authenticated users.

cscc-cli no longer falls back to an internal Kubernetes service name. On a new machine, provide the public API URL explicitly with --api-url or CSCC_API_URL. The value may include /api/v1; the CLI normalizes it automatically.

cscc-cli login --api-url https://api.cscc.nthu.edu.tw --username alice

The CLI prompts for your password and calls /api/v1/cli/login. This flow does not use CAPTCHA and does not require X-API-Key.

On success, the CLI stores a cscc_... user API token in its local config file with 0600 permissions. The backend stores only a SHA-256 hash of the token, so the cleartext token is shown only once during creation.

Optional token name:

cscc-cli login --api-url https://api.cscc.nthu.edu.tw --username alice --name workstation

Import a dashboard-created token¶

You can also create an API token from Settings → API Key & CLI in the dashboard and import it into cscc-cli:

cscc-cli login --api-url https://api.cscc.nthu.edu.tw --token cscc_...

The CLI verifies the token with /api/v1/auth/status before saving it. This is useful when browser login is already available and you do not want to type your password in the terminal.

Stateless token override¶

For automation, set CSCC_API_TOKEN instead of saving local config:

CSCC_API_URL=https://api.cscc.nthu.edu.tw CSCC_API_TOKEN=cscc_... cscc-cli whoami

CSCC_DEV_TOKEN is still accepted as a deprecated compatibility alias, but new scripts should use CSCC_API_TOKEN.

TLS / Internal CA¶

Official cscc-cli releases include the platform internal root CA, so most users do not need to download a certificate separately. If the platform root CA is rotated, download the newly published CLI binary before reconnecting.

Manual CA configuration is still available for custom CLI builds, emergency CA rotation windows, and TLS troubleshooting:

Env	Description
`CSCC_API_URL`	API base URL, e.g. `https://api.cscc.nthu.edu.tw/api/v1`
`CSCC_API_TOKEN`	Optional stateless `cscc_...` token override
`CSCC_API_CA_CERT_PATH`	One or multiple PEM files separated by `,` or `;`
`CSCC_API_TLS_SERVER_NAME`	Optional TLS SNI name (fallback to config if not set)
`SSL_CERT_FILE`	Path to a PEM file containing the internal root CA
`REQUESTS_CA_BUNDLE`	Alternative env path for a PEM bundle containing the internal root CA

Example:

CSCC_API_CA_CERT_PATH=/Users/me/platform-internal-root-ca.pem \
  cscc-cli login --api-url https://api.cscc.nthu.edu.tw --username alice

Advanced: download and trust CLI CA from settings¶

Open https://dashboard.cscc.nthu.edu.tw/settings and open API Key & CLI.

Use this only when you are running a custom CLI build, testing a CA rotation, or debugging TLS trust. The official CLI already has the platform CA embedded.

Click Download CLI CA to save platform-internal-root-ca.pem.
Run the install command generated by the dashboard.
Verify the CLI connection with the manual CA override:

CSCC_API_CA_CERT_PATH=~/.config/cscc-cli/platform-internal-root-ca.pem \
  CSCC_API_URL=https://api.cscc.nthu.edu.tw \
  cscc-cli whoami

If you prefer not to set the env each time, place platform-internal-root-ca.pem or ca.crt into ~/.config/cscc-cli/; the CLI auto-detects those names after checking explicit env and saved config paths.

Check Identity¶

cscc-cli whoami

This verifies the saved token and prints the current user and role information. Role changes take effect immediately because authorization is resolved from the backend RBAC/Casbin state on each request.

Build Images¶

Upload mode is the default and accepts a directory, a .tar.gz, or a .zip archive:

cscc-cli build --project <project-id> --name trainer --tag v1.0.1 .
cscc-cli build --project <project-id> --name trainer ./context.tar.gz

For directories, the CLI packs the target directory into a .tar.gz build context. The context or uploaded archive must contain a root-level Dockerfile.

Dockerfile-only mode matches the dashboard's pasted-Dockerfile flow and calls /api/v1/images/build/dockerfile:

cscc-cli build --source dockerfile \
  --project <project-id> \
  --name trainer \
  --tag v1.0.1 \
  --dockerfile ./Dockerfile

cat Dockerfile | cscc-cli build --source dockerfile \
  --project <project-id> \
  --name trainer \
  --dockerfile -

Storage mode builds from a readable platform storage path and calls /api/v1/images/build/from-storage:

cscc-cli build --source storage \
  --project <project-id> \
  --name trainer \
  --storage-source personal \
  --storage-path apps/trainer

cscc-cli build --source storage \
  --project <project-id> \
  --name trainer \
  --storage-source project_storage \
  --storage-id <storage-id> \
  --storage-path apps/trainer

Useful options:

Option	Description
`--project`	Project ID that owns the image build
`--name`	Short image name, for example `trainer-api`
`--tag`	Optional image tag. Omit it to use the platform default
`--source`	`upload`, `dockerfile`, or `storage`
`--dockerfile`	Dockerfile path, or `-` for stdin, when `--source dockerfile`
`--storage-source`	`personal` or `project_storage` when `--source storage`
`--storage-path`	Source path inside the selected storage
`--storage-id`	Project storage ID for `project_storage` builds
`--cpu-cores`	Optional CPU request for the build job
`--memory-gb`	Optional memory request in GiB
`--timeout-minutes`	Optional build timeout override
`--follow=false`	Submit the build without streaming logs

After submission, --follow=true polls until build logs are available, streams /api/v1/images/build/:jobName/logs?follow=true, and stops with the final completed, failed, or deleted status when the backend reports one.

The CLI reads the API endpoint from --api-url during login/import, then from CSCC_API_URL, then from saved config. There is no internal-service fallback. Use the gateway API host for production:

export CSCC_API_URL=https://api.cscc.nthu.edu.tw

The build request and log stream use the user token created by cscc-cli login:

Authorization: Bearer cscc_...

No CSCC_API_KEY, PLATFORM_API_KEY, or X-API-Key header is required for CLI builds. The project must have Image Build Permission enabled, and your project role must allow builds.

Token Management¶

List active API tokens:

cscc-cli tokens list

Revoke a token by ID:

cscc-cli tokens revoke <token-id>

Log out from the current machine:

cscc-cli logout

Logout first calls DELETE /api/v1/me/api-tokens/current to revoke the currently used token, then keeps TLS settings in config and clears local token fields so manual certificate overrides can be reused.

Defaults¶

Setting	Default	Description
`USER_API_TOKEN_TTL_HOURS`	`2160`	Token lifetime in hours (90 days)
`USER_API_TOKEN_MAX_ACTIVE`	`20`	Maximum active tokens per user
`CLI_LOGIN_MAX_ATTEMPTS`	`5`	Failed login attempts before lockout
`CLI_LOGIN_LOCKOUT_SECONDS`	`900`	Lockout window in seconds