Operate your iFrame fleet 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 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>.

iframe keys list inst-...
# [
#   {
#     "grant_id":"…",
#     "linux_user":"cust_kmpkhm5q_alice",
#     "pubkey_fingerprint":"SHA256:…",
#     "pubkey_type":"ed25519",
#     "status":"active",
#     "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 underlying default user (e.g. ec2-user, ubuntu). Combined with the iFrame-isolation AppArmor + iptables profile shipped with the orchestrator, tenants on shared nodes cannot see each other.

iframe keys add <id> --user <label> --pubkey <path> [--note <text>]
  --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

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

Refuses with exit 5 when the instance lifecycle is not live. Refuses with exit 2 on a malformed label or unparseable public key.

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.