CLI Reference

CLI Reference#

The kinetic command line tool handles infrastructure provisioning, cluster management, and job status.

kinetic#

kinetic: Provision and manage GCP infrastructure for remote Keras execution.

Usage

kinetic [OPTIONS] COMMAND [ARGS]...

Options

--profile <profile_name>#: Use a named profile for this invocation [env: KINETIC_PROFILE].

--version#: Show the version and exit.

Environment variables

KINETIC_PROFILE: Provide a default for --profile

accelerators#

List supported accelerator types and their configurations.

Usage

kinetic accelerators [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

--live#: Check cluster for provisioned (hot) accelerators.

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

build-image#

Build and push prebuilt base images.

Builds one image per accelerator category (cpu, gpu, tpu) using Cloud Build and pushes them to the specified repository. Supports both Docker Hub and Artifact Registry — the target is detected automatically from the –repo value.

When –repo is omitted the command enters interactive mode and guides you through registry selection and configuration.

This command works for both kinetic maintainers publishing official images and users who want their own base images in a private registry.

Usage

kinetic build-image [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

--repo <repo>#: Image repository — Docker Hub (e.g. ‘kinetic’) or Artifact Registry (e.g. ‘us-docker.pkg.dev/my-project/kinetic-base’). Omit to select interactively.

--category <category>#

Accelerator categories to build (default: all)

Options:: cpu | gpu | tpu

--tag <tag>#: Image version tag (default: kinetic package version)

--dockerfile <dockerfile>#: Path to a custom Dockerfile. When set, it is used instead of the auto-generated one. The Dockerfile must install uv, cloudpickle, google-cloud-storage, and COPY remote_runner.py to /app/.

--update-credentials#: Re-enter Docker Hub credentials even if they already exist

-y, --yes#: Skip confirmation prompt

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

config#

Show kinetic configuration.

Usage

kinetic config [OPTIONS] COMMAND [ARGS]...

show#

Show current configuration.

Usage

kinetic config show [OPTIONS]

down#

Tear down kinetic GCP infrastructure.

Usage

kinetic down [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

-y, --yes#: Skip confirmation prompt

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

init#

Onboard: detect environment, pick a cluster, save an active profile.

Usage

kinetic init [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

--profile-name <profile_name>#: Profile name to save (default: cluster name).

--namespace <namespace>#

Kubernetes namespace to record in the saved profile [env: KINETIC_NAMESPACE]

Default:: 'default'

-y, --yes#: Skip confirmation prompts.

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

KINETIC_NAMESPACE: Provide a default for --namespace

jobs#

Inspect and manage async remote jobs.

Usage

kinetic jobs [OPTIONS] COMMAND [ARGS]...

cancel#

Cancel a running job by deleting its k8s resource.

Usage

kinetic jobs cancel [OPTIONS] JOB_ID

Options

--cleanup-poll-interval <cleanup_poll_interval>#

Seconds between k8s deletion-confirmation polls.

Default:: 2

--cleanup-timeout <cleanup_timeout>#

Maximum seconds to wait for k8s resource deletion.

Default:: 180

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Arguments

JOB_ID#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

cleanup#

Clean up Kubernetes and/or GCS resources for a job.

Usage

kinetic jobs cleanup [OPTIONS] JOB_ID

Options

--k8s, --no-k8s#: Delete Kubernetes resources.

--gcs, --no-gcs#: Delete uploaded GCS artifacts.

--cleanup-poll-interval <cleanup_poll_interval>#

Seconds between k8s deletion-confirmation polls.

Default:: 2

--cleanup-timeout <cleanup_timeout>#

Maximum seconds to wait for k8s resource deletion.

Default:: 180

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Arguments

JOB_ID#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

debug#

Attach a debugger to a running debug-enabled job.

Sets up kubectl port-forward and prints VS Code attach configuration. Blocks until Ctrl+C or the job completes, then tears down the tunnel.

Usage

kinetic jobs debug [OPTIONS] JOB_ID

Options

--port <port>#: Local port for debugpy port-forwarding.

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Arguments

JOB_ID#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

list#

List live async jobs.

Usage

kinetic jobs list [OPTIONS]

Options

--output-dir <output_dir>#: Output directory [env: KINETIC_OUTPUT_DIR]

--namespace <namespace>#

Kubernetes namespace [env: KINETIC_NAMESPACE]

Default:: 'default'

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Environment variables

KINETIC_OUTPUT_DIR: Provide a default for --output-dir

KINETIC_NAMESPACE: Provide a default for --namespace

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

logs#

Show or stream logs for a job.

Usage

kinetic jobs logs [OPTIONS] JOB_ID

Options

-f, --follow#: Stream logs until completion.

-n, --tail <tail>#: Show the last N log lines instead of the full log.

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Arguments

JOB_ID#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

result#

Wait for and print a job result.

Usage

kinetic jobs result [OPTIONS] JOB_ID

Options

--timeout <timeout>#: Maximum seconds to wait for the result.

--cleanup, --no-cleanup#: Delete k8s and GCS artifacts after collecting the result.

--cleanup-poll-interval <cleanup_poll_interval>#

Seconds between k8s deletion-confirmation polls.

Default:: 2

--cleanup-timeout <cleanup_timeout>#

Maximum seconds to wait for k8s resource deletion.

Default:: 180

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Arguments

JOB_ID#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

status#

Show the current status for a job.

Usage

kinetic jobs status [OPTIONS] JOB_ID

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Arguments

JOB_ID#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

pool#

Manage accelerator node pools.

Usage

kinetic pool [OPTIONS] COMMAND [ARGS]...

add#

Add an accelerator node pool to the cluster.

Usage

kinetic pool add [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

--accelerator <accelerator>#: Required Accelerator spec: t4, l4, a100, a100-80gb, h100, v5litepod, v5p, v6e, v3 (with optional count/topology)

--min-nodes <min_nodes>#: Minimum node count for the accelerator node pool (default: 0)

-y, --yes#: Skip confirmation prompt

--spot#: Use Spot VMs for node pool

--preview#: Preview infrastructure changes without applying them

--reservation <reservation>#: GCP capacity reservation name to consume when provisioning nodes [env: KINETIC_RESERVATION]

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

KINETIC_RESERVATION: Provide a default for --reservation

list#

List accelerator node pools on the cluster.

Usage

kinetic pool list [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

remove#

Remove an accelerator node pool from the cluster.

Usage

kinetic pool remove [OPTIONS] POOL_NAME

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

-y, --yes#: Skip confirmation prompt

--preview#: Preview infrastructure changes without applying them

Arguments

POOL_NAME#: Required argument

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

profile#

Manage named kinetic profiles (project/zone/cluster/namespace bundles).

Usage

kinetic profile [OPTIONS] COMMAND [ARGS]...

create#

Create a new profile.

Any unset field is resolved in this order:: –<flag> > KINETIC_* env var > interactive prompt.

Usage

kinetic profile create [OPTIONS] [NAME]

Options

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

--zone <zone>#: GCP zone [env: KINETIC_ZONE]

--cluster <cluster_name>#: GKE cluster name [env: KINETIC_CLUSTER]

--namespace <namespace>#: Kubernetes namespace [env: KINETIC_NAMESPACE]

--force#: Overwrite an existing profile with the same name.

Arguments

NAME#: Optional argument

Environment variables

KINETIC_PROJECT: Provide a default for --project

KINETIC_ZONE: Provide a default for --zone

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_NAMESPACE: Provide a default for --namespace

ls#

List all saved profiles.

Usage

kinetic profile ls [OPTIONS]

rm#

Delete a profile.

Usage

kinetic profile rm [OPTIONS] NAME

Options

-y, --yes#: Skip confirmation.

Arguments

NAME#: Required argument

show#

Show a profile’s settings.

Default target: the profile selected by –profile / KINETIC_PROFILE, or the stored active profile if neither was provided.

Usage

kinetic profile show [OPTIONS] [NAME]

Arguments

NAME#: Optional argument

unset#

Clear the active profile pointer. Saved profiles are preserved.

Usage

kinetic profile unset [OPTIONS]

use#

Set name as the active profile.

Usage

kinetic profile use [OPTIONS] NAME

Arguments

NAME#: Required argument

status#

Show current kinetic infrastructure state.

Usage

kinetic status [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

up#

Provision GCP infrastructure for kinetic.

Usage

kinetic up [OPTIONS]

Options

--cluster <cluster_name>#: GKE cluster name [default: kinetic-cluster]

--zone <zone>#: GCP zone [env: KINETIC_ZONE, default: us-central1-a]

--project <project>#: GCP project ID [env: KINETIC_PROJECT]

--force-destroy, --no-force-destroy#: Whether kinetic buckets get auto-emptied on teardown. Use –no-force-destroy to require manually emptying buckets before ‘kinetic down’. Persisted across commands [env: KINETIC_FORCE_DESTROY, default: force-destroy]

--accelerator <accelerator>#: Accelerator spec: cpu, t4, l4, a100, a100-80gb, h100, v5litepod, v5p, v6e, v3

--min-nodes <min_nodes>#: Minimum node count for accelerator node pools (default: 0, scale-to-zero)

--profile-name <profile_name>#: Profile name to save (default: cluster name).

--namespace <namespace>#

Kubernetes namespace to record in the saved profile [env: KINETIC_NAMESPACE]

Default:: 'default'

-y, --yes#: Skip confirmation prompt

--preview#: Preview infrastructure changes without applying them

Environment variables

KINETIC_CLUSTER: Provide a default for --cluster

KINETIC_ZONE: Provide a default for --zone

KINETIC_PROJECT: Provide a default for --project

KINETIC_FORCE_DESTROY: Provide a default for --force-destroy

KINETIC_NAMESPACE: Provide a default for --namespace

CLI Reference

Contents

CLI Reference#

kinetic#

accelerators#

build-image#

config#

show#

down#

init#

jobs#

cancel#

cleanup#

debug#

list#

logs#

result#

status#

pool#

add#

list#

remove#

profile#

create#

ls#

rm#

show#

unset#

use#

status#

up#