Operate your iFrame estate from the terminal.

iframe login

Save an API key for a profile to ~/.iframe/credentials (mode 0600). Prompts for the key on stdin.

iframe login [--profile <name>] [--api-url <url>]
  --profile  default  profile name  (also: IFRAME_PROFILE)
  --api-url           API base URL  (default: https://cloud.iframe.ai)

iframe logout

Remove a saved profile from the credentials file.

iframe logout [--profile <name>]

iframe whoami

Inspect the active credentials, the bound organization, and the scopes on the active key.

iframe whoami
# table:
# API URL : https://cloud.iframe.ai
# Key ID  : kmpkhm5qeprr
# Key name: ci pipeline
# Org     : Acme (org-uuid)
# Scopes  : instances:read, instances:lifecycle, usage:read

iframe doctor

Diagnose connectivity, key validity, and the bound org. Useful as a CI smoke check.

iframe doctor
# config:        OK (api_url=https://cloud.iframe.ai)
# auth:          OK (key=kmpkhm5qeprr, scopes=5)
# org binding:   Acme (org-uuid)
# api version:   v1

iframe instances list

List every iFrame instance in the active org. Lifecycle is always re-derived from the live cloud-provider state at the boundary; the value you see is current as of the request.

iframe instances list [--state live|halted|transient|unknown|all]
  --state  filter by canonical lifecycle  (default: shows everything)

Bad --state values are rejected with exit 2 and a list of valid values.

iframe instances get <id>

Show full details for one iFrame instance: lifecycle, IPs, attached volumes, hardware specs, rate, contract dates.

iframe instances get inst-123e4567-e89b-12d3-a456-426614174000
# Returns 404 / exit 4 if the id does not exist in your org.

iframe instances status <id>

Liveness probe: the canonical lifecycle, plus an out-of-band SSH reachability check with latency and a redacted reason on failure.

iframe instances status inst-...
# {
#   "lifecycle": "live",
#   "public_ip": "203.0.113.42",
#   "ssh": { "ssh_reachable": true, "latency_ms": 38 }
# }

iframe instances reboot <id>

Soft reboot via in-OS systemctl reboot --no-block. Preserves the instance's identity, public IP, private IP, and root volume. The cloud-provider lifecycle API is never called, so any underlying reservation remains intact.

iframe instances reboot inst-... [-y|--yes]
  -y, --yes  skip the interactive confirmation prompt

# Refuses with exit 5 if lifecycle != live; the reply includes the
# current lifecycle so scripts can branch:
# {"error":"Soft reboot unavailable: instance is halted — start it first",
#  "exit_code":5,"lifecycle":"halted"}

iframe instances reprovision <id>

Rebuild the instance from its original launch image — a "clean slate" reset that preserves every piece of identity that matters and wipes everything that doesn't. Three steps run in order:

1. Root replacement. The root volume is replaced from the same launch image the instance was originally provisioned from. Instance ID, public IP, private IP, and the underlying reservation are preserved.
2. Ephemeral wipe. Every non-root NVMe instance-store device is blkdiscard'd. Persistent data volumes are not touched.
3. Soft reboot. Issued at the hypervisor level so the new root sees a clean kernel. Skipped automatically if step 2 wiped nothing.

iframe instances reprovision inst-... [-y|--yes]
  -y, --yes  skip the interactive confirmation prompt

# Returns immediately with a task_id; the orchestrator drives the
# rest in the background. Track progress with `iframe instances get`:
#   lifecycle             — `live` once back online
#   last_reprovision_state — pending → in-progress → succeeded
#   last_cleanup           — wipe_state and reboot_state
#
# Refuses with exit 5 if lifecycle != live or another reprovision
# is already in flight on the same instance.

SSH grants survive automatically. Active grants stored against the instance are replayed onto the new root: each cust_* user is recreated, its public key is reauthorized, and its --sudo flag is restored. Grants created before pubkey persistence (legacy) are marked pending_resync and must be re-issued by the customer.

iframe keys list <id>

List active and revoked SSH grants on an iFrame instance. Each grant maps an SSH public key to a per-customer Linux user named cust_<keyId8>_<label>. The sudo field reflects whether the grant was created with --sudo.

iframe keys list inst-...
# [
#   {
#     "grant_id":"…",
#     "linux_user":"cust_kmpkhm5q_alice",
#     "pubkey_fingerprint":"SHA256:…",
#     "pubkey_type":"ed25519",
#     "status":"active",
#     "sudo": false,
#     "created_at":"2026-04-26T07:48:56Z"
#   }
# ]

iframe keys add <id>

Land a customer-scoped Linux user with a public key. The user is named cust_<keyId8>_<label> and never shares the default OS user (ubuntu). Linux users are created on the live node over the orchestrator's admin SSH channel — no provider-specific handoff is exposed to the caller.

iframe keys add <id> --user <label> --pubkey <path>
                       [--note <text>] [--sudo]
  --user    label segment, [a-z0-9-]{2,16}, becomes part of cust_…_…
  --pubkey  path to a public key file (or '-' to read stdin)
  --note    optional, free-form note saved with the grant
  --sudo    grant the cust_ user NOPASSWD:ALL via /etc/sudoers.d/.
            Off by default — opt in per grant.

# Example — no sudo (default)
iframe keys add inst-... --user alice --pubkey ~/.ssh/alice.pub
# {
#   "grant_id":"…",
#   "linux_user":"cust_kmpkhm5q_alice",
#   "pubkey_fingerprint":"SHA256:…",
#   "sudo": false,
#   "ssh_login_hint":"ssh cust_kmpkhm5q_alice@203.0.113.42"
# }

# Example — opt-in NOPASSWD root
iframe keys add inst-... --user alice --pubkey ~/.ssh/alice.pub --sudo

When --sudo is set, the orchestrator validates a single <linux_user> ALL=(ALL) NOPASSWD:ALL line with visudo -cf before installing it as /etc/sudoers.d/iframe-<linux_user> (mode 0440, owned by root). The flag is recorded on the grant and replayed automatically across instances reprovision. Refuses with exit 5 when lifecycle is not live; exit 2 on a malformed label or unparseable public key; exit 6 if the orchestrator can't reach the instance over its admin channel.

iframe keys remove <id> <grantId>

Revoke an SSH grant and remove the Linux user. If the instance is currently live the user is deleted in-OS over SSH; if not, the grant is marked revoked in the database and the user is removed automatically the next time the node is live.

iframe keys remove inst-... <grant-id>
# {
#   "revoked": true,
#   "ssh_cleanup": { "attempted": true, "ok": true },
#   "message": "Linux user removed and grant revoked"
# }

iframe usage

Per-resource accrued cost for a calendar month. Defaults to the current month. Same numbers your dashboard shows.

iframe usage [--month YYYY-MM]
  --month  defaults to the current calendar month

# Output (JSON)
# {
#   "period": "2026-04",
#   "total_accrued": 4321.56,
#   "currency": "USD",
#   "items": [
#     {
#       "iframe_id":"inst-…",
#       "lifecycle":"live",
#       "rate_per_hour":2.50,
#       "rate_per_month":1800.00,
#       "accrued_cost":1234.50,
#       "days_with_cost_records":21
#     }
#   ]
# }

A malformed --month is rejected with exit 2.

iframe billing invoices

List invoices for the active org. Optional --year filter.

iframe billing invoices [--year YYYY]

iframe billing invoice <period>

Show one invoice. <period> is YYYY-MM.

iframe billing invoice 2026-04
# Returns 404 / exit 4 if the invoice does not exist.
# Bad period strings are rejected with exit 2.

iframe instances webhook *

Per-instance signed webhook for node-disruption events. Configure, rotate, test, list deliveries, and remove. Full reference, payload contract, signature recipe, and a drop-in receiver live on a dedicated page.

iframe instances webhook set       <id> --url <https-url> --events advisory,warning,offline
iframe instances webhook get       <id>
iframe instances webhook rotate    <id>
iframe instances webhook test      <id> [--event advisory|warning|offline]
iframe instances webhook deliveries <id> [--limit N]
iframe instances webhook remove    <id>

Requires scope instances:webhook. See Notifications for the wire format, the three event severities, the HMAC recipe, and a zero-dependency Node receiver.