> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing instances from the CLI

> Use the Tinfoil CLI to manage the full instance lifecycle without opening the dashboard.

The [Tinfoil CLI](https://github.com/tinfoilsh/tinfoil-cli) lets you manage projects and individual instances, along with model weights, secrets, SSH keys, registry credentials, and custom domains.

This page walks through the full instance lifecycle from the terminal.

## Prerequisites

Install or update to the latest published CLI by running the installer:

```bash theme={"dark"}
curl -fsSL https://github.com/tinfoilsh/tinfoil-cli/raw/main/install.sh | sh
```

Or download a binary from the [releases page](https://github.com/tinfoilsh/tinfoil-cli/releases). A Docker image is published at `ghcr.io/tinfoilsh/tinfoil-cli`.

Check your installation with `tinfoil --version`.

You also need a Tinfoil organization with Tinfoil Containers enabled, the same prerequisite as the [quickstart](https://docs.tinfoil.sh/containers/quickstart.md).

### Updating the CLI

Check for a newer stable release or install it without logging in:

```bash theme={"dark"}
tinfoil update --check
tinfoil update
```

This updates only the CLI executable, not your running workloads, configuration, or keys. See [Updating the CLI](https://docs.tinfoil.sh/sdk/cli-sdk.md#updating-the-cli) for JSON output, permissions, and package-manager guidance.

## Authenticating

Container management requires an **organization admin API key**. A personal admin key selects a personal context and cannot manage organization instances. Create an organization key by following [Getting a Tinfoil admin key](https://docs.tinfoil.sh/admin/get-admin-key.md), then run:

```bash theme={"dark"}
tinfoil login                        # prompts for the key (no shell history)
tinfoil login --api-key admin_xxx    # non-interactive, e.g. for CI
tinfoil whoami                       # confirm the effective credential and context
tinfoil logout                       # delete the saved credential
```

Credentials are written to `~/.tinfoil/config.json` with mode `0600`. `whoami` checks the effective credential with the server and displays its organization or personal context, user ID, API URL, and credential source. For an organization context, it shows the returned organization ID; do not infer an organization from a key prefix or the GitHub repository owner.

These environment variables can override saved configuration:

| Variable | Purpose |
| - | - |
| `TINFOIL_ADMIN_KEY` | Highest-priority admin credential override |
| `TINFOIL_API_KEY` | Admin credential override only when its value starts with `admin_`; an inference key does not replace the saved admin login |
| `TINFOIL_TUNNEL_API_KEY` | Inference key (`tk_...`) for `tinfoil forward` and `tinfoil ssh` |
| `TINFOIL_CONTROLPLANE_URL` | Tinfoil management API base URL |
| `TINFOIL_CONFIG` | Alternate CLI configuration file path |
| `TINFOIL_NO_UPDATE_CHECK` | Set to `1` to disable passive update notices, not explicit `tinfoil update` or `tinfoil update --check` |

> [!NOTE]
>
> Credential precedence is `TINFOIL_ADMIN_KEY`, then an admin key in `TINFOIL_API_KEY`, then the saved file. Logging in saves a key but does not unset environment overrides; logging out removes only the saved file. To switch organizations, clear or change active overrides, log in with the intended organization's key, and check `tinfoil whoami` again.

## Inspecting your organization

```bash theme={"dark"}
tinfoil project list          # repositories and aggregate instance counts
tinfoil project get myorg/my-app-config
tinfoil container list           # all instances in the org
tinfoil container get my-app     # full detail for one instance
tinfoil container hosts          # which container hosts your org may target
```

Pass `-o json` to get machine-readable output suitable for scripting:

```bash theme={"dark"}
tinfoil container list -o json | jq '.[] | select(.status == "failed")'
tinfoil container get my-app -o json
```

Projects can be referenced by **repository name** (`owner/repo`) or **project UUID**. Instances can be referenced by **name** or **instance UUID**. If a debug-mode and a production-mode instance share a name, the CLI lists both and asks for the UUID.

## Publishing a config release

Before a tag can be deployed, the config repo must publish a measured release. In the dashboard, open the repository's config editor under **Containers**, edit `tinfoil-config.yml`, open and **merge** the generated pull request, then follow the **Release** steps.

Alternatively, commit the config change in GitHub and run the **Tinfoil Release** workflow from the repository's **Actions** tab. Wait for both release workflow phases to finish before deploying the tag. See [Updating](https://docs.tinfoil.sh/containers/updates.md#starting-an-update) for both workflows.

The same flow is available from the CLI with `tinfoil repo`, which acts through the Tinfoil GitHub App installed on the repository:

```bash theme={"dark"}
# Read the current tinfoil-config.yml from the default branch
tinfoil repo config get myorg/my-app-config
tinfoil repo config get myorg/my-app-config --raw > tinfoil-config.yml

# Open a pull request with a locally edited config (use - to read from stdin)
tinfoil repo config pr myorg/my-app-config --file ./tinfoil-config.yml --body "Bump memory"
tinfoil repo pr status myorg/my-app-config 42

# Inspect release tags and trigger the Tinfoil Release workflow
tinfoil repo build info myorg/my-app-config
tinfoil repo build run myorg/my-app-config --version v0.0.1
tinfoil repo build status myorg/my-app-config --version v0.0.1
```

Merge the config PR on GitHub before `repo build run`; `repo pr status` must report `Merged: true`. `repo build run` only queues a release. `repo build status` checks its workflow without dispatching another run; also follow the GitHub Actions link and verify both tag creation and measurement/publication succeed. `repo build info` reports tags and published releases; confirm the **same tag** is published before creating the instance. It also suggests the next patch version. The build command accepts semver and adds the `v` prefix if missing. The repository must be public, so never put secret values in `tinfoil-config.yml`.

## Creating an instance

Once `v0.0.1` is measured and published, create an instance using that exact tag. For the template, [create its `GREETING_TOKEN` secret first](https://docs.tinfoil.sh/containers/quickstart#4-add-the-demo-secret):

```bash theme={"dark"}
tinfoil container create my-app \
  --repo myorg/my-app-config \
  --tag v0.0.1
```

| Flag | What it does |
| - | - |
| `--repo` | GitHub `owner/repo` containing `tinfoil-config.yml` (required) |
| `--tag` | Release tag to deploy (required) |
| `--variable KEY=VALUE` | Environment variable; repeatable |
| `--secret NAME` | Organization or repository secret to mount; repeatable |
| `--ssh-key NAME` | Org SSH key (debug instances only); repeatable |
| `--debug` | Deploy in [debug mode](https://docs.tinfoil.sh/containers/debug-mode.md) |
| `--mark-latest=false` | Leave the repository's latest GitHub release unchanged (defaults to `true`) |
| `--custom-domain` | Use a [verified custom domain](https://docs.tinfoil.sh/containers/custom-domains.md) |
| `--host` | Pin to a specific host (see `tinfoil container hosts`) |
| `--volume ID_OR_NAME[:MOUNT_NAME]` | **Beta.** Attach an existing [managed volume](https://docs.tinfoil.sh/containers/encrypted-volumes.md#create-and-attach-a-volume) to a named mount and deploy; repeatable |
| `--replace ID` | Stop and remove an existing instance before queuing its replacement |

The command follows the deployment, printing observed boot stages until the instance is **Running**, and exits non-zero if it observes a failure. Pass `--no-wait` or `-o json` to return the initial response without following progress. Create also records the project and revision you typed in your [connection policy](https://docs.tinfoil.sh/sdk/cli-sdk.md#connection-policy), so the first `connect` from this machine does not prompt.

Before updating anything, send the [first verified request](https://docs.tinfoil.sh/containers/quickstart.md#6-make-a-verified-request), using the reported domain and `myorg/my-app-config@v0.0.1`. Optional flags above are for applications that need them; a custom domain must already be verified, and selected secrets must already exist.

A named volume mount requires a disk only when it declares `key-secret` (JSON `key_secret`). Pass `--volume` for each required mount; optional mounts may remain empty. If required mounts exist and you omit `--volume`, `create` refuses before creating the instance and prints the `volume create` and `container create --volume` commands to run. See [Create and attach a volume](https://docs.tinfoil.sh/containers/encrypted-volumes.md#create-and-attach-a-volume).

Initial creates cannot be held for review. Marking the tag as the repository's latest
GitHub release defaults to `true`; pass `--mark-latest=false` to leave it
unchanged. It happens only when the GitHub App is connected, the repository is
active, and an initial or changed tag is running on a non-debug instance.

Explicit `--host` selection requires host-selection access for the organization,
and the selected host and GPU size must be available to it. `--replace` is
destructive: the old instance is stopped and removed before the replacement is
queued. If the replacement later fails, the old instance is not restored.

## Managing projects

One project contains all instances in your organization that use the same GitHub repository. Inspect its aggregate status and instance counts with:

```bash theme={"dark"}
tinfoil project list
tinfoil project get myorg/my-app-config
```

Set whether eligible project updates use [hold for review](https://docs.tinfoil.sh/containers/hold-for-review.md) by default:

```bash theme={"dark"}
tinfoil project settings myorg/my-app-config --hold-by-default=true
```

Individual `container update` operations, including config-only updates, and batch `project update` operations inherit this setting when `--hold` is omitted. An explicit value applies only to that operation; it does not change the project default. Creates and deploys are never held.

Update all running instances to one release:

```bash theme={"dark"}
tinfoil project update myorg/my-app-config --tag v1.0.1
```

To update only selected instances, repeat `--instance` with each instance UUID:

```bash theme={"dark"}
tinfoil project update myorg/my-app-config \
  --tag v1.0.1 \
  --mark-latest=false \
  --instance 550e8400-e29b-41d4-a716-446655440000 \
  --instance 6ba7b810-9dad-11d1-80b4-00c04fd430c8
```

Pass `--hold=true` or `--hold=false` to override the project's default for one update. Use `=`: a space-separated boolean is parsed as another positional argument. Holding applies only to blue/green updates (CPU-only and single-GPU instances without persistent volumes). If preflight finds an eligible instance whose target release requires replacement, a held project update is rejected before any instance is updated. Only running instances are updated; stopped and failed instances are skipped (bring them up with `container deploy`), as are instances with an update already in progress. Without a hold, replacement updates require downtime confirmation; pass `--yes` in scripts. After preflight, results are reported per instance, and the command exits non-zero if any instance is skipped or fails.

Marking the tag as the latest release defaults to `true` and happens for each changed tag once it is running and serving production, subject to the repository and GitHub App conditions described above. For held updates it happens after promotion. Pass `--mark-latest=false` to leave the latest release unchanged.

## Lifecycle

An instance is either running or it is not. `deploy` boots an enclave for an instance that has none; `update` replaces the version a running instance serves. To run the same version on a fresh enclave, `update` a blue/green instance to its current tag (no downtime), or `stop` and then `deploy` any instance (downtime).

```bash theme={"dark"}
# Stop a running instance (saved settings and persistent volumes remain)
tinfoil container stop my-app

# Deploy a stopped or failed instance (optionally with config overrides)
tinfoil container deploy my-app
tinfoil container deploy my-app --tag v1.0.1
tinfoil container deploy my-app --volume dev-disk:workspace
tinfoil container deploy my-app --host gpu-host-2

# Update a running instance to a new tag or configuration
tinfoil container update my-app --tag v1.0.1
tinfoil container update my-app --tag v1.0.1 --hold=true
tinfoil container update my-app --tag v1.0.1 --mark-latest=false
tinfoil container update my-app --variable LOG_LEVEL=debug
tinfoil container update my-app --secret NEW_KEY --secret OTHER_KEY

# Delete (irreversible; prompts unless --yes)
tinfoil container delete my-app
```

`deploy` and `update` support `--tag`, `--variable`, `--secret`, `--ssh-key`, `--debug`, `--mark-latest`, and `--custom-domain`. `deploy` also supports `--volume` and `--host`; `update` also supports `--hold`. Supplied variables replace the full saved per-instance variable map; they do not replace the measured `env` values in `tinfoil-config.yml`. In managed delivery, a supplied secret list replaces the saved manual selection, then merges with declared secrets that exist in repository or organization scope. Supplied SSH-key lists replace their saved selections.

`--secret` selects managed secrets, never private-keyserver names. A non-debug
private target requires an empty managed selection; omitting `--secret` does not
clear saved bindings. Pass a single `--secret=""` to send `"secrets": []` on an
individual create, deploy, or update; do not combine it with named selections.
When switching to private delivery, also remove colliding saved variables with
a complete replacement map. See the [CLI and API transition example](https://docs.tinfoil.sh/containers/private-secrets.md#switching-an-existing-instance-to-private-delivery).
Never upload private values as a workaround. In managed delivery, declared
secrets are still merged after clearing the manual selection.

A running instance cannot change hosts. Stop it, then deploy it with `--host`. Host access and GPU entitlement are validated when you select a host. A volume cannot automatically move to another host.

When deploying after a stop, wait until the instance is **Stopped** before changing its tag, host, or disk attachments. A deploy queued while it is **Stopping** retains the current tag, host, and disk attachments. `deploy --volume` must attach the disk first, so it fails rather than queueing if the instance is still **Stopping**.

`deploy`, `update`, and `promote` follow progress, printing observed boot stages and exiting non-zero if they observe a failure. A held update returns when the candidate is ready for review, without switching production traffic; other successful operations finish when the instance is **Running** and the update has completed. Pass `--no-wait` or `-o json` to return the initial response without following progress.

> [!WARNING]
>
> `tinfoil container delete` permanently removes the instance, its secret bindings, and its DNS records. There is no undo. Managed volumes are retained as unattached disks; delete them separately to erase their data.

## Updates and downtime

Before submitting an update, the CLI prints a read-only [current-to-target plan](https://docs.tinfoil.sh/containers/updates.md#reviewing-the-change): tags, CPU/RAM/GPU resources, strategy and downtime, effective hold and its source, changed setting names, retained volume data, and whether to mark GitHub latest. No secret values are printed. The plan is not a historical snapshot or a reservation; the server validates the update again when it is submitted.

When the plan includes `secret_delivery`, the CLI distinguishes managed and
external secret names and states that private-keyserver authorization and unlock
are not verified. JSON output preserves this optional object and its
`external_secrets_verified: false` field; see the [response schema](https://docs.tinfoil.sh/admin/admin-api.md#secret-delivery-in-update-plans).

CPU-only and single-GPU instances without persistent volumes update blue/green: the new version boots alongside the current one and traffic switches once it is running. Multi-GPU instances and instances with persistent volumes cannot run two copies, so `update` stops the current version first and deploys the new one in its place. The CLI describes the downtime and asks you to type `yes` before proceeding; pass `--yes` in scripts. `tinfoil container get` shows `Updates: replace` for instances whose updates cause downtime.

```bash theme={"dark"}
tinfoil container get my-app       # shows the in-progress update and its stage
tinfoil container promote my-app    # switch traffic to a held update that is ready
tinfoil container cancel my-app    # discard the new version, keep the current one
```

When [held for review](https://docs.tinfoil.sh/containers/hold-for-review.md), a blue/green update that is ready waits for `container promote` while the current enclave serves production. Otherwise traffic switches automatically. `container cancel` discards the new version without changing the production-serving instance; it also clears a failed update. Updates that replace the running instance cannot be held or canceled once the current version has stopped.

## Volumes

Manage [encrypted persistent volumes (Beta)](https://docs.tinfoil.sh/containers/encrypted-volumes.md) with `tinfoil volume`:

```bash theme={"dark"}
tinfoil container hosts                                   # volumes live on one host
tinfoil volume create my-db-data --size 16GB --host HOST_NAME
tinfoil volume list
tinfoil volume attach my-db-data my-db --as data          # instance must be stopped
tinfoil volume detach my-db-data                          # keeps the data
tinfoil volume rename my-db-data --name archive-data
tinfoil volume delete archive-data                        # erases the data; must be detached
```

`--size` takes decimal units such as `16GB` or `2TB`, and every volume counts toward your [storage limit](https://docs.tinfoil.sh/containers/limits.md#infrastructure-tiers) until it is deleted. Attach and detach require the instance to be stopped. Pass `--volume` to `container create` or `container deploy` to attach and deploy in one step.

## Secrets

Manage organization secrets with `tinfoil secret`:

```bash theme={"dark"}
tinfoil secret list

# Create
tinfoil secret create DATABASE_URL --value-file ./db.url
echo -n "$STRIPE_KEY" | tinfoil secret create STRIPE_SECRET_KEY --value-file -

# Update value (instances using it are marked stale; update them to pick up the new value)
tinfoil secret set DATABASE_URL --value-file ./db.url

# Inspect (the value itself is never returned)
tinfoil secret get DATABASE_URL

# Delete (fails if any instance references it)
tinfoil secret delete DATABASE_URL
```

Secrets scoped to a single repository use `tinfoil repo secret` with the same subcommands and flags:

```bash theme={"dark"}
tinfoil repo secret list myorg/my-app-config
tinfoil repo secret create myorg/my-app-config DATABASE_URL --value-file ./db.url
tinfoil repo secret set myorg/my-app-config DATABASE_URL --value-file -
tinfoil repo secret get myorg/my-app-config DATABASE_URL
tinfoil repo secret delete myorg/my-app-config DATABASE_URL
```

Repository secrets are also available from the **Project secrets** section of the repository's config editor under **Containers** in the dashboard.

The same secret name can have different values in different repositories. An organization secret and a repository secret cannot share a name within the same organization.

`--value-file` accepts `-` for stdin, which is the recommended way to set secrets because it keeps the value out of shell history and process listings. See [secrets and env vars](https://docs.tinfoil.sh/containers/secrets-and-env-vars.md) for the underlying model.

## SSH keys

[Debug-mode](https://docs.tinfoil.sh/containers/debug-mode.md) instances authorize SSH access using public keys registered at the org level:

Choose one of the supported input forms:

```bash theme={"dark"}
tinfoil ssh-key list

# Read from a file
tinfoil ssh-key create laptop --public-key-file ~/.ssh/id_ed25519.pub

# Or read from stdin
cat ~/.ssh/id_ed25519.pub | tinfoil ssh-key create laptop --public-key-file -

# Or pass the public key inline
tinfoil ssh-key create laptop --public-key "ssh-ed25519 AAAA..."

tinfoil ssh-key delete laptop
```

Reference keys with `--ssh-key NAME` on `tinfoil container create`, `deploy`, or `update`.

## Registry credentials

For [private images](https://docs.tinfoil.sh/containers/private-images.md), set credentials per registry. The CLI supports `ghcr`, `gcr`, and `dockerhub`; configure ECR and custom registries in the dashboard or through the [Admin API](https://docs.tinfoil.sh/admin/admin-api.md#registry-credentials).

```bash theme={"dark"}
tinfoil registry list

# GitHub Container Registry: classic PAT with read:packages
tinfoil registry set ghcr --username my-gh-user --token ghp_xxx

# Google Artifact Registry / Container Registry: service-account JSON
tinfoil registry set gcr --key-file ./gcp-sa.json

# Docker Hub: PAT with read permission
tinfoil registry set dockerhub --username my-docker-user --token dckr_xxx

# Remove credentials for a registry
tinfoil registry delete ghcr
```

## Custom domains

```bash theme={"dark"}
tinfoil domain list

# Register a domain, then add its traffic and certificate CNAME records
tinfoil domain add api.example.com

# Re-check DNS after configuring records
tinfoil domain verify api.example.com

# Remove (fails if any instance uses it)
tinfoil domain delete api.example.com
```

Once a domain is verified, deploy an instance against it with `tinfoil container create ... --custom-domain api.example.com`. See [custom domains](https://docs.tinfoil.sh/containers/custom-domains.md) for the DNS record details and troubleshooting.

## Model weights

For GPU inference instances, `tinfoil model` prepares Hugging Face weights as
verified artifacts that enclaves load with integrity checking. See
[Model weights](https://docs.tinfoil.sh/containers/models.md) for how the pieces fit together.

```bash theme={"dark"}
# Wrap a model on a host; --wait prints the tinfoil-config.yml block when done
tinfoil model wrap google/gemma-4-31B-it --host gpu-host-1 --wait

# Gated or private repos
tinfoil model wrap meta-llama/Llama-4-8B --host gpu-host-1 --hf-token-file ./hf.token

# Update a previously wrapped model to its latest (or a specific) revision
tinfoil model update google/gemma-4-31B-it --host gpu-host-1 --wait

# Inspect wrap jobs
tinfoil model list
tinfoil model status gpu-host-1 <job-id>   # add --logs for wrap logs

# Delete a wrap job (removes the artifact once nothing references it)
tinfoil model delete gpu-host-1 <job-id>
```

`wrap` pins the repo's latest default-branch commit unless `--commit` is
given. `update` requires an existing completed wrap of the repo on that host
and resolves the newest commit when `--commit` is omitted; when an update run
with `--wait` completes, it prints the new `models:` block along with the
delete command for the previous wrap job. Run that delete only after the new
config is released and deployed. `delete` is refused while a job is running
or while any instance on the host references the artifact.

## Connecting to a deployed instance

> [!NOTE]
>
> **Beta:** Verified connections use [V3 attestation](https://docs.tinfoil.sh/resources/feature-status.md), which is still being deployed. This designation applies to connection verification and V3-dependent features, rather than ordinary instance management.

`tinfoil container connect <name>` resolves the production connection's domain and config reference, checks the resolved config against your local [connection policy](https://docs.tinfoil.sh/sdk/cli-sdk.md#connection-policy), then runs a verified local proxy pinned to that config. It saves you from looking up those values and passing them to `tinfoil proxy -e <domain> -r <repo>@<tag>` by hand:

```bash theme={"dark"}
# Interactive: the first connect shows the resolved config and asks you to
# confirm it (unless container create already seeded it); after that it's silent.
tinfoil container connect my-app -p 3301

# Scripts (no terminal) state their expectation instead of answering a prompt.
# The resolved config must fall under the reference, which is then remembered:
tinfoil container connect my-app -p 3301 --repo myorg/my-app-config          # any revision
tinfoil container connect my-app -p 3301 --repo myorg/my-app-config@v0.0.2  # exactly this one

# Skip the policy check for one invocation; nothing is remembered:
tinfoil container connect my-app -p 3301 --dangerous
```

For a blue/green candidate, use `tinfoil container connect my-app --review -p 3301`. It pins the candidate tag and refuses if no review connection is available; it never falls back to production. `container get` and deployment progress output print available URLs with verified HTTP request commands. See [Hold for review](https://docs.tinfoil.sh/containers/hold-for-review.md#using-the-cli).

The proxy binds to `127.0.0.1` by default. Pass `--bind <ADDRESS>` to use another interface:

```bash theme={"dark"}
tinfoil container connect my-app --port 3301 --bind 0.0.0.0
```

Only bind beyond localhost on a trusted network because other hosts may then send requests through the proxy.

In another terminal, send requests to `http://localhost:3301` exactly as you would to your instance's domain. The proxy verifies attestation on startup and pins the TLS certificate for subsequent requests. See [connecting](https://docs.tinfoil.sh/containers/connecting.md) for the full client story (SDKs, raw `tinfoil http`).

> [!WARNING]
>
> Debug-mode instances do not pass attestation, so `connect` (and any other `SecureClient` flow) will refuse to use them. SSH into debug instances directly via `ssh -p <port> root@debug.tinfoil.sh`. The dashboard shows the exact command on the instance's card.

### Connection policy

Inspect or configure the policy that gates these connections with the `trust`
command — the file is `~/.tinfoil/known-configs.yml`, yours to edit, and the
CLI preserves your comments when it writes:

```bash theme={"dark"}
tinfoil trust                             # show mode, record, and the allow list
tinfoil trust set --mode frozen           # unknown configs fail instead of prompting
tinfoil trust set --record pin --prune    # record exact pins; remove broader entries
```

See the [connection policy](https://docs.tinfoil.sh/sdk/cli-sdk.md#connection-policy) reference for the
file format, matching rules, and script guidance.

## Resource metrics

```bash theme={"dark"}
tinfoil container metrics my-app --time 24h
```

Returns a JSON object with `data_points` and `interval`. Each data point has a timestamp, average and maximum CPU/GPU utilization, average and maximum CPU/GPU memory utilization, and CPU/GPU total memory. `interval` is the width of each time bucket. This is useful for piping into `jq` or a chart tool.

## Scripting tips

* `-o json` is supported on every list/get command.
* Exit codes are non-zero on failure, with the API error message printed to stderr.
* All commands respect the environment overrides listed above, so the CLI is safe to use from CI. Store the admin key as a secret and pass it through the environment instead of running `tinfoil login`.
* `--verbose` and `--trace` increase log verbosity for debugging connectivity issues.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.