Axern CLI

axern is the product CLI for resources and interactive development. It talks to public APIs through gatewayd; it never connects directly to node or database internals.

Confirm the current context

axern context list
axern context current

For a local machine, the recommended path creates and manages the context for you:

axern local up

For a Helm installation, keep a gateway port-forward open and import the deployment-owned administrator mTLS identity. SSH is optional and disabled by the default chart values, so the basic CLI path only needs the control port:

kubectl --namespace axern-system port-forward svc/gatewayd 25100:25000

axern context import-kubernetes local \
  --namespace axern-system \
  --endpoint 127.0.0.1:25100 \
  --ssh-endpoint "" \
  --current

Use the Kubernetes install guide when an interactive agent workflow also needs the separately enabled SSH port.

Diagnose the platform

Start with the read-only platform doctor. It validates the selected context, mTLS certificate lifetime and key permissions, gateway connectivity, and namespace access without creating resources:

axern doctor --namespace default

Use an explicit probe when control-plane reachability is not enough:

axern doctor --namespace default --probe

The probe creates a temporary Environment from the explicit OCI image passed with --image, executes a small runsc Run, and deletes the Environment after the Run reaches a terminal state. The Run remains as normal control-plane history. JSON output exposes stable check codes without printing certificate paths, private keys, raw endpoints, or server error text. Doctor exits with 0 for healthy, 1 for degraded, 2 for invalid usage or connection configuration, and 3 when a required platform health check fails.

Use axern identity whoami to inspect the Principal, active certificate, and effective roles for the selected context. Platform administrators can manage durable Principals and namespace bindings with axern admin principal, axern admin credential, and axern admin role-binding. See Identity and namespace access for the least-privilege workflow.

Run isolated Python

axern run docker.io/library/python:3.12-slim -- \
  python -c 'import platform; print(platform.python_version())'

Use a strict resource file when a specification should be reviewed or reused:

run.yaml

api_version: axern/v1
kind: Run
metadata:
  namespace: default
  labels:
    example: docs
spec:
  source:
    image: docker.io/library/python:3.12-slim
  command:
    argv: [python, -c, "print('ok')"]
  resources: {}

axern run --file run.yaml

OCI images are the explicit workload source. Reuse a resolved Environment when multiple Runs need the same immutable input.

By default, run attaches to stdout/stderr and exits with the remote command’s exit code. Use --detach for asynchronous creation, then inspect it with axern run get, axern run list, or axern run logs --follow. The Runs guide covers the full lifecycle, spec fields, and Allocation-local output availability.

Pass credentials without putting values in argv

Prefer stdin for opaque secrets. This keeps the value out of command arguments. Referencing an existing environment variable also avoids writing the value literally in the command or heredoc history, but the variable remains visible to the local CLI process:

printf '%s\n' "API_KEY=$AXERN_SECRET_API_KEY" | \
  axern secret create --namespace default --literal-stdin

The CLI deliberately does not accept opaque secret values as command-line arguments.

The CLI help is authoritative for the complete flag surface. See the CLI source guide for contexts, exit codes, aliases, Runs, tunnels, and admin workflows.