Configuration reference

Global flags, environment variables, persistent state on disk, the --json envelope and the semantic exit codes. Everything you need to drive the CLI from a script (or from a coding agent inside an IDE) without parsing prose.

Global flags

Every command accepts these. The CLI reads them from process.argv before subcommand parsing, so they work wherever you put them on the line.

--version (or -v) is a root shortcut rather than a per-command flag. Alone on the line it prints two lines and exits 0: the CLI's own version, then the agent protocol contract version this binary advertises.

$ stackbone --version
stackbone-cli 0.3.3
contract 15

Environment variables

The CLI reads these from the parent shell:

Either model-provider variable also opens the first-run gate. Export one and stackbone dev never stops for setup: it goes straight to your workflows and agents. See The first run.

Running two projects at once

One stackbone dev session owns a fixed set of ports, so a second one on the same machine collides. STACKBONE_DEV_PORT_OFFSET shifts the whole set: the API port, and the Postgres, Redis and MinIO containers behind it.

STACKBONE_DEV_PORT_OFFSET=1 stackbone dev   # API on :4252, Postgres on :5443, …

Each step of the offset is worth 10 ports. 0 (the default) keeps the ports you already know. An explicit --port always wins for the API port, but the containers still shift, so pass the offset rather than only overriding --port.

stackbone dev also injects the env vars your agents and workflows read through the ambient stackbone client (STACKBONE_POSTGRES_URL, WORKFLOW_REDIS_URL, STACKBONE_AGENT_ID, …). See SDK integration → how the CLI connects to the SDK.

State on disk

Per-machine (global)

Lives under ~/.stackbone/:

Per-machine (cache)

Per-project

Lives at the project root:

Keeping a package out of the bundle

stackbone dev and stackbone build compile your deep agents the same way: each deep-agents/<name>/index.ts is bundled into a single index.mjs next to it, with your own dependencies inlined. The local run and the deployed container behave alike because production resolves no dependencies a second time.

A few packages break when you bundle them: ones with a native binary, a WASM asset, or that read their own files from disk at runtime. Name those in build.external and they stay bare imports, resolved from the box's node_modules at boot:

import { defineWorkspace } from '@stackbone/sdk';

export default defineWorkspace({
  agents: [],
  workflows: [],
  build: { external: ['sharp'] },
});

The list applies to both paths. stackbone build records the full effective set in the bundle manifest and warns about it at the end of the build, so whoever packages the image knows which packages to install alongside it. Nothing installs them for you. The image carries a node_modules decided at image build time, so add these packages yourself, at the same versions this workspace uses. Miss one and the agent fails to start with ERR_MODULE_NOT_FOUND.

@stackbone/sdk, deepagents and @langchain/* are always external, because exactly one copy of each has to exist per process. You never list them.

The compiled index.mjs is a build artifact: stackbone init already gitignores deep-agents/*/index.mjs.

Output contract

Human mode (default)

Free-form text on stdout. May span multiple lines, may include @clack/prompts chrome and ANSI colour codes. Never parse this. Logging (debug, trace, deprecation warnings) goes to stderr through Pino regardless of mode.

JSON mode

Trigger it with --json or STACKBONE_JSON=1. Every command emits a single JSON line on stdout wrapped in:

// success
{ "schema_version": 1, ...payload }

Errors go on stderr and include the original exit code:

{
  "schema_version": 1,
  "error": {
    "code": "auth",
    "message": "No active session for https://api.stackbone.ai",
    "suggestion": "Run `stackbone login`",
  },
  "exit_code": 2,
}

schema_version is an integer that only bumps on backward-incompatible shape changes. If a coding agent sees a value greater than the one it was written against, it should refuse to parse and surface the version mismatch.

Paginated lists

A cursor-paginated list command (runs list, hitl list, the storage, rag and db table listings) takes --limit <n> and --cursor <opaque>, and its JSON payload carries an items array plus nextCursor and prevCursor (either may be null). To walk forward, pass the previous page's nextCursor value back as --cursor. Some lists add domain-specific fields alongside items (for example common_prefixes on a storage listing); on a paginated list the three keys are always present and always shaped the same way. A short list (stackbone list, stackbone workflows list) returns everything at once, with no cursor keys.

{
  "schema_version": 1,
  "items": [
    /* … */
  ],
  "nextCursor": "eyJ…",
  "prevCursor": null,
}

Exit codes

error.code in the JSON envelope carries the same decision at a finer grain. Five names match the rows above one for one (generic, auth, no_project, not_found, permission). The rest fold into one of those exit codes and keep a name of their own, so a caller can tell two failures with the same integer apart:

Branch on the integer for the coarse answer, on error.code when you need the distinction. Neither needs the message parsed:

# In a shell script
if ! out=$(stackbone whoami --json 2>err); then
  case "$(jq -r '.error.code' < err)" in
    auth)       stackbone login ;;
    not_found)  echo "stale session" ;;
    *)          echo "unexpected: $out" ; exit 1 ;;
  esac
fi

The six exit codes are stable across CLI releases, so scripts and coding agents can pin to them. A new error.code name can appear inside an exit code that already exists, so treat a name you do not recognise as its integer.

Putting it together

A coding-agent-friendly invocation looks like:

STACKBONE_JSON=1 stackbone metadata

It produces one line describing the organization state.

Not on this page: the stackbone config document

This page is about CLI and on-disk configuration: flags, env vars, and the files that live in your project. It is not about the versioned AGENT_CONFIG document your running agents and workflows read at runtime through the ambient client (stackbone.config.get(...)). That runtime config is its own surface, edited with the stackbone config command family (get, set, versions, rollback, types) and shaped by a config.schema.ts in your project. See the config module reference.