internal-platform-cli

name

internal-platform-cli

description

Use whenever a task touches the internal platform via the `axle` CLI — deploying a service, reading or rotating secrets, tailing logs, running one-off commands or migrations in an environment, or inspecting env config. Reach for this any time you are about to run `axle ...`, or when a command "worked locally" but hung, targeted the wrong environment, or silently hit prod instead of staging. Especially load this before anything destructive (`axle deploy`, `axle db migrate`, `axle secrets set`, `axle exec`) or anything run from CI / a non-interactive shell.

internal-platform-cli

Overview

axle is the internal platform CLI — the single wrapper engineers use to operate services on the platform: deploys, secrets, logs, one-off command execution, database access, and environment config. Every invocation runs against a context (an auth identity) and a target environment (staging or prod). The two are independent, and the most expensive mistakes come from a command quietly resolving to the wrong one. axle is built for humans at a TTY by default; running it from CI or a script without the right flags is the second-biggest source of failures.

When to Use

Use this skill when you are:

• Deploying or rolling back a service (axle deploy, axle deploy --rollback).
• Reading, setting, or rotating secrets (axle secrets get|set|rotate).
• Tailing or querying logs (axle logs), especially live tail.
• Running a one-off command, shell, or migration inside a running service (axle exec, axle db).
• Inspecting or diffing environment configuration (axle env).
• Writing a CI step, cron, or script that shells out to axle (non-TTY).
• Debugging a command that hung, paged, or hit the wrong environment.

Do NOT use this for: local-only development (use the service's own make/npm scripts), CI pipeline definition syntax (that's the ci.yaml schema, not axle), or cloud-provider console operations that bypass the platform. axle is the platform's front door; if a task is genuinely outside the platform, it won't help.

See references/commands.md for the full subcommand surface, flags, and worked examples. Load it whenever you need exact flag names or output formats.

Context & environment model

Two orthogonal selectors decide what an axle command actually does:

• Context = who you are (auth identity + cluster credentials). Set with axle context use <name>, shown by axle context current. Stored in ~/.axle/config. A stale or wrong context is why "permission denied" and "service not found" appear for services you know exist.
• Environment = what you target (staging | prod). Resolved in this order: explicit --env/-e flag → AXLE_ENV var → the context's default env. There is no global default of staging — if a context's default is prod, a bare command hits prod.

Make the target explicit on anything that writes. The safe habit is axle <cmd> -e staging ... / -e prod ... every time, rather than trusting the resolved default.

Typical flow

axle context current                 # confirm WHO and default env before anything
axle deploy api -e staging           # ship to staging, watch rollout
axle logs api -e staging --since 5m  # verify health
axle deploy api -e prod              # promote (prompts for confirmation on prod)

For machine output (CI, parsing), add --json and --no-pager:

axle logs api -e prod --since 1h --no-pager --json | jq '.[] | select(.level=="error")'

Gotchas

ALWAYS treat these as real, observed failure modes — each has bitten someone operating a live service.

• A bare command does NOT default to staging — it resolves to the context's default env, which may be prod. New engineers assume "no --env means safe/staging." It doesn't. If your current context's default is prod, axle deploy api deploys to production. Always pass -e staging / -e prod explicitly on any write (deploy, secrets set, db migrate, exec). Run axle context current first to see the default. Treat an unflagged write command in a script as a bug.

• Context and environment are independent — being "in" staging context does not stop -e prod from working. Context selects credentials; if your identity has prod access, an -e prod flag (or AXLE_ENV=prod left exported in your shell) reaches prod regardless of which context is "current." Check both: axle context current shows context AND resolved default env. A lingering export AXLE_ENV=prod from an earlier session is a classic silent foot-gun — unset AXLE_ENV when in doubt.

• axle logs (live tail) and other interactive subcommands open a pager and BLOCK under non-TTY. In CI, a cron, or piped output, axle logs without flags will hang forever waiting on a pager / streaming tail that never gets a terminal. From any non-interactive context, always pass --no-pager and a bounded --since/--limit (live --follow tail never returns — don't use it in scripts). axle exec and axle db shell similarly try to allocate a TTY and fail or hang non-interactively; use axle exec -- <cmd> (one-shot, non-interactive) instead of an interactive shell.

• Destructive subcommands prompt for confirmation, and that prompt is what hangs your automation — don't blindly add --yes. axle deploy -e prod, axle db migrate, axle db reset, and axle secrets rotate require typed confirmation (often re-typing the service or env name for prod). In a script this prompt blocks on stdin forever. The fix is --yes/ to pre-confirm — but on or removes the only guardrail, so gate it behind an explicit, reviewed CI condition, never reflexively. There is no undo for .

Files

• references/commands.md — full subcommand reference for deploy, secrets, logs, exec, db, and env: every flag, output format, exit codes, and worked examples (including CI-safe non-TTY invocations).