Account and organization

These five commands are the read-only view of who you are signed in as and which organization the CLI is pointed at. All of them need a session, so a signed-out shell gets exit code 2, and each one wraps its --json output in the shared { "schema_version": 1, ... } envelope.

stackbone whoami

Show the active user and organization.

JSON payload

{
  "schema_version": 1,
  "user": { "id": "...", "email": "..." },
  "organization": { "id": "...", "slug": "...", "name": "..." },
  "control_plane_url": "https://api.stackbone.ai",
}

Exit codes: 0 ok, 2 auth.

stackbone current

Print the organization the CLI acts as. Tab-separated <slug>\t<name> in human mode.

This is the organization stackbone organization use selected. The CLI falls back to the first organization in your membership list if you never made a choice, or if the organization you chose is no longer one you belong to. whoami resolves it the same way.

JSON payload

{
  "schema_version": 1,
  "organization": { "id": "...", "slug": "...", "name": "..." },
}

Exit codes: 0 ok, 2 auth, 4 not found (you belong to no organization).

stackbone list

List the organizations you belong to. Tab-separated table in human mode (SLUG\tNAME\tID), or the line (no organizations) when the list is empty.

JSON payload

{
  "schema_version": 1,
  "organizations": [{ "id": "...", "slug": "...", "name": "..." }],
}

Exit codes: 0 ok, 2 auth.

stackbone organization use

stackbone organization use [slug]

Choose which organization the CLI acts as. If you belong to more than one organization, this sets the active organization for the current control plane. stackbone init, stackbone link and stackbone dev use it to create or resolve a workspace. The CLI stores the choice per environment in ~/.stackbone/credentials.json, so logging into a different control plane keeps its own selection.

This setting does not affect an already-created project: it stays with the organization recorded in its .stackbone/project.json. To work in a specific organization, switch first, then create the project there:

stackbone organization use            # interactive picker (TTY)
stackbone organization use acme       # switch straight to a slug

# Create a workspace inside a chosen org:
stackbone organization use acme        # 1. make "acme" active
stackbone init my-app --with agent     # 2. the new workspace is registered in "acme"

With a slug argument it switches directly (works in CI and --json).
With no argument and a TTY it shows a picker of the organizations you belong to, marking the current one. If you belong to only one, it confirms that one.
In non-interactive mode (no TTY, --json, or -y) with several organizations and no slug, it exits asking you to pass the slug.

JSON payload

{
  "schema_version": 1,
  "organization": { "id": "...", "slug": "...", "name": "..." },
}

Exit codes: 0 ok, 2 auth (not logged in), 4 not found (a slug you don't belong to, or no organization at all), 1 generic (several organizations and no slug in non-interactive mode).

stackbone metadata

One-shot agent-friendly overview: replaces whoami + current + list for callers that want a single payload to plan from. Today it returns organization, user and an empty agents / publications / channels array. The shape is stable across releases, so coding agents can rely on it: the empty arrays and the remote: null are declared placeholders, and a payload that carries them came from a call that succeeded.

JSON payload

{
  "schema_version": 1,
  "cli_version": "0.3.3",
  "control_plane_url": "https://api.stackbone.ai",
  "user": { "id": "...", "email": "..." } /* or null */,
  "organization": { "id": "...", "slug": "...", "name": "..." } /* or null */,
  "agents": [],
  "publications": [],
  "channels": [],
  "runtime": {
    "local": { "running": false },
    "remote": null,
  },
}

cli_version is the version of the CLI that answered, so a coding agent can branch on it instead of guessing from the output shape.

Exit codes: 0 ok, 2 auth, 4 not found (you belong to no organization).