Configuration

Environment variables

sling is configured entirely through the environment — there are no config files beyond the credential it writes at ~/.config/sling/credentials.

SLING_HOST

Env-only by design — there is no --host flag. It must be https:// (or http:// on a loopback development host) so the token never travels in cleartext.

How agents authenticate

On your own machine, an agent needs nothing extra. sling login writes the session to ~/.config/sling/credentials for your user, so any agent running as you picks it up. Sign in once and the agent is authenticated.

See API credentials for the credentials the control plane accepts and the scopes each endpoint needs.

Context resolution

sling resolves the org and repo it is acting on so that in-repo invocations need zero addressing:

• Org is auto-resolved when unambiguous, overridable with --org <slug>, and persisted as a default by sling org switch. Multi-org accounts do not pay a flag tax on every call.
• Repo is detected from the git remote of the current directory, overridable with --repo <owner/name>.

Global flags

Available on the root command and every subcommand.

Machine mode is one switch with individually available parts:

Output streams

stdout carries data only. Human chrome — summary rows, spinners, prompts — goes to stderr. This happens unconditionally: the CLI does not check whether stderr is a TTY, so the same spinner and cursor-control sequences land on stderr even when it is redirected to a file or piped into another process. Don't rely on TTY detection to decide whether chrome is present — pipe stderr to /dev/null if you need to suppress it silently. That still leaves the more important case: on a prompt-bearing command like sling logout, --json by itself only changes what stdout serializes as — it does not imply --yes/--no-input, so a script passing --json alone still blocks on the confirmation prompt. --agent is the flag that guarantees non-interactive behavior, since it bundles --yes and --no-input; reach for --agent, not bare --json, in anything unattended. A failed command usually writes nothing to stdout: a bad id makes sling runs show <bad-id> --agent exit 3 with zero bytes on stdout. sling logs is the exception — asked for a real job that stores no logs it exits 3 and emits its envelope ({ "lines": [], "has_more": false, "local": { ... } }). Branch on $?, not on whether stdout is empty.

That is what makes sling usage --json | jq safe to pipe unconditionally: on failure jq receives empty input rather than half a table.

JSON casing is set per endpoint, not by whether the field crossed the network. Nearly every control-plane response sling passes through — top, labels, usage, bill, runs, jobs, resolve, why, time — is snake_case and frozen, matching its API schema. GET /api/whoami is the confirmed exception: it is a real control-plane call like any other (a bad SLING_HOST makes sling whoami --agent fail with exit 5, the same as any other command that reaches the API), but its schema is camelCase end-to-end (userId, githubLogin, expiresAt). The local envelope described below is composed by the CLI rather than passed through, but every key observed inside it so far is a single lowercase word (org, kind, slug, plan), so its casing convention for a multi-word key is not yet established by any shipped response. Don't infer a command's casing from "was this local" — check that command's reference page, or default to expecting snake_case and treat whoami as the documented exception.

The control-plane response, when there is one, is passed through verbatim at the top level of the JSON, with a sibling local key recording what the CLI resolved (org, repo, etc.) — not nested inside a wrapper. local is not on every response: sling top, sling usage, sling runs list and sling whoami all carry it, while sling labels list returns { "labels": [ ... ] } with no local key at all, so treat it as optional when parsing. For example (values redacted):

{
  "by": "workflow",
  "metric": "runner-minutes",
  "window": { "from": "2026-07-25T22:47:14.510Z", "to": "2026-08-24T22:47:14.510Z" },
  "rows": [
    { "key": "ci", "repo": "example-repo", "runner_minutes": 69559, "cost_usd": 556.47, "p50_ms": 69000, "p95_ms": 180000, "p99_ms": 358540, "queue_wait_ms": 14000, "trend_pct": 170.7 }
  ],
  "local": { "org": "example-org" }
}

{
  "identity": { "userId": "example-user-id", "name": "Example User", "email": "user@example.com", "githubLogin": "example-login" },
  "credential": { "type": "session", "expiresAt": "2026-08-31T20:38:25.617Z" },
  "local": { "org": { "kind": "set", "slug": "example-org", "plan": "paid" } }
}

Note the casing split across these two commands: runner_minutes, cost_usd, and p50_ms (the sling top control-plane fields) are snake_case, while userId, githubLogin, and expiresAt (the sling whoami control-plane fields) are camelCase — whoami calls the control plane the same as top does, its response schema is just camelCase. In both examples, the local block is camelCase-shaped regardless of the surrounding response's casing.

sling logs differs by mode, and the difference runs the opposite way to the rest of this page. In human mode it streams raw log lines to stdout, so | head and | less behave as you would expect, exiting cleanly when the pipe closes early. Under --agent or --json it returns a structured envelope like every other command — { "lines": [ ... ], "has_more": ..., "local": { ... } }, one object per line — so a machine caller can hand logs to the same JSON parser it uses everywhere else rather than special-casing it.

Exit codes

Every command exits from one table, so a script or agent can branch on $? without parsing output.

Codes 3, 4, 5, and 7 are mapped by a shared error handler, so any command can surface them. See API errors for the HTTP responses behind each.

Read a command's exit code with $? immediately after it, since the next command overwrites it:

sling doctor; echo $?
10   # 0 = healthy, 10 = unhealthy