Getting Started

This guide takes you from zero to a running experiment: install the CLI, log in, pick a cluster, submit a workload, and read its status and logs. Each step shows the command and the kind of output you'll see.

Quickstart

1. Install the CLI

The Falcon repository is private, so build the falcon binary from source:

git clone https://github.com/primatrix/Falcon
cd Falcon
go build -o /tmp/falcon ./apps/falcon

Put /tmp/falcon somewhere on your PATH (or call it by full path). The CLI talks to the production Falcon server by default — no extra config needed for daily use.

2. Log in

falcon auth login

This opens your browser to the Cloudflare Access login page and stores the issued token under ~/.config/falcon/credentials.json. On success:

Login successful for https://falcon.infiscale-infra.org

On a headless machine the CLI prints the login URL to your terminal — open it on any other device and the login still completes.

3. See available clusters

falcon cluster list

You'll see something like:

CLUSTER_ID    NAME           PROJECT             LOCATION     TPU_TYPE  STATUS   CREATED_AT
cl-7af2k9qd   tpu7x-cluster  tpu-service-473302  us-central1  v7x       active   2026-04-12 09:31 CST

You need at least one cluster with STATUS active to submit work. If there isn't one, ask an operator to register or activate a cluster.

4. Submit an experiment

Describe the workload in a YAML file. This minimal example runs a trivial command on one v7x chip:

cat <<EOF > experiment.yaml
name: trial-001
exp_type: training
cluster_name: tpu7x-cluster
artifact_type: hlo
role_to_task_spec:
  worker:
    command: "echo hello && sleep 5"
    replica: 1
    image: "busybox:1.37"
    device_type: "v7x"
    device_topo: "2x2x1"
EOF

falcon exp create -f experiment.yaml

Falcon creates the experiment, its backing job, and an artifact, and prints their IDs:

EXP_ID          JOB_ID          ARTIFACT_ID   NAME       STATUS   ARTIFACT_URI
exp-arf29g1hql  job-8kd2m1xqp4  art-9plzq2v8  trial-001  pending  gs://.../experiments/exp-arf29g1hql/artifacts/art-9plzq2v8/

Note the EXP_ID — you'll use it for everything below.

By default Falcon chooses the cluster's configured supply path. To force a GKE flex-start node pool, set supply_mode: flex-start under the role's task spec. See Experiment Lifecycle for the full example and caveats.

5. Check status

falcon exp get exp-arf29g1hql

exp_id:       exp-arf29g1hql
name:         trial-001
status:       running
exp_type:     training
cluster:      tpu7x-cluster
job_id:       job-8kd2m1xqp4
job_status:   RUNNING
conditions:
  - type:                 ResourceReady
    status:               True
    reason:               reservation
  - type:                 K8sJobSubmitted
    status:               True
    reason:               Submitted
artifact_id:  art-9plzq2v8
artifact_uri: gs://.../experiments/exp-arf29g1hql/artifacts/art-9plzq2v8/

status walks created → pending → running → succeeded | failed. The conditions block is the durable scheduling/provisioning trail — useful when an experiment sits in pending longer than expected.

6. Read logs

falcon exp logs exp-arf29g1hql

This streams the workload pod's stdout/stderr through Falcon — no direct Kubernetes access needed. Add -f to follow a live run.

Prerequisites

• CLI binary — built from source as in step 1.

• Server URL — defaults to the production endpoint. Override per call with --server <addr> or set FALCON_SERVER=<addr> in your shell.

• Credentials — interactively, falcon auth login (humans). For CI / automation, set a Cloudflare Access service token instead:

  export FALCON_CF_ACCESS_CLIENT_ID='<id>.access'
  export FALCON_CF_ACCESS_CLIENT_SECRET='<secret>'

• An active cluster — at least one row with STATUS active in falcon cluster list.

Core commands

Command	What it does
falcon exp create -f <yaml>	Submit an experiment
falcon exp get <exp_id>	Show status, conditions, artifact
falcon exp list	List your experiments
falcon exp logs <exp_id>	Stream workload logs (-f to follow)
falcon exp abort <exp_id>	Stop a running experiment
falcon exp exec <exp_id> -- <cmd>	Run a command inside a live pod
falcon exp inspect <exp_id>	Render a reproduction manifest
falcon exp delete <exp_id>	Remove an experiment record

Next steps

• Experiment Lifecycle — the full submit → inspect → re-run → abort flow, GCS mounts, and Git credentials.
• Analyzer Workflow — run analyzers over an artifact and read the reports, including a profile-a-workload example.

Scripting & automation

Every command supports --output json for scripts and CI to consume a stable machine-readable form instead of the human tables above. For agent- and pipeline-friendly workflows (submit, wait, collect, analyze), see the falcon-workflow skill, which wraps these commands behind a locked JSON envelope.