Scion CLI Reference

The Scion CLI is the primary interface for managing agents, projects, and server components.

Global Flags

These flags are available on all commands:

• -g, --project <string>: Project identifier: path, slug (with Hub), or git URL (with Hub).
• --global: Use the global project (equivalent to --project global).
• -p, --profile <name>: Configuration profile to use.
• --format <string>: Output format (json or plain).
• --hub <url>: Hub API endpoint URL (overrides SCION_HUB_ENDPOINT).
• --no-hub: Disable Hub integration for this invocation (local-only mode).
• -y, --yes: Skip confirmation prompts.
• --non-interactive: Full non-interactive mode (implies --yes, errors on ambiguous prompts).
• --debug: Enable verbose debug output.

Decluttered CLI Help

To keep subcommand help output clean and readable, global flags are hidden from default subcommand help outputs. You can view the full list of global flags anytime by running:

scion help global-flags

Agent Lifecycle

scion start (or run)

Starts a new agent or resumes an existing one. Starting a suspended agent implicitly resumes its harness session (continuing the prior conversation); starting a stopped or error agent runs a fresh session. See scion suspend and scion resume.

Usage: scion start <agent-name> [task] [flags]

• Arguments:
  • <agent-name>: Unique name for the agent instance.
  • [task]: (Optional) The initial instruction/task for the agent.
• Flags:
  • -b, --branch <string>: Target branch for the agent workspace.
  • -t, --type <string>: Template to use (default “gemini”).
  • -i, --image <string>: Override container image.
  • -a, --attach: Attach to the agent immediately after starting.
  • --no-auth: Disable authentication propagation.
  • -d, --detached: Run in detached mode (default true).
  • --config <path>: Path to inline agent config file (YAML/JSON) for Just-In-Time (JIT) overrides, or - for stdin.
  • --harness-config <string>: Named harness configuration to use.
  • --harness-auth <string>: Override auth method for the harness. Universal types: api-key, oauth-token, vertex-ai, auth-file (each harness accepts a subset — see Harness Authentication).
  • --broker <string>: Preferred runtime broker ID or name for execution.
  • --message-mode <mode>: Set the agent’s initial message mode (project, branch, lineage, none, or hub). Defaults to project. See Message Authorization & Modes.
  • --notify: Get notified via the browser or system when the spawned agent reaches a terminal state.

scion stop

Stops a running agent. This is a graceful shutdown (SIGTERM); the agent’s phase becomes stopped and the next start runs a fresh session.

Usage: scion stop <agent-name>

scion suspend

Suspends a running agent, preserving its harness session for a later resume. Unlike stop, suspending sets the agent’s phase to suspended, and the next start (or resume) continues the prior conversation instead of starting fresh.

Only running agents can be suspended, and the agent’s harness must support session resume (Claude Code and Gemini CLI do; the generic harness does not — use stop instead). See Agent Lifecycle.

Usage: scion suspend <agent-name> [flags]

• Flags:
  • -a, --all: Suspend all running agents in the current project. Agents whose harness does not support resume are skipped.

scion resume

Resumes an existing agent. For a suspended agent, the harness session is continued (Claude Code receives --continue, Gemini CLI --resume, etc.). For a stopped agent, there is no session to continue, so a fresh session is started.

A plain scion resume <agent-name> (no task) simply continues the prior session — the agent’s original creation task is not re-injected. If you pass an explicit prompt, it is sent as a new message on top of the continued session.

Usage: scion resume <agent-name> [task] [flags]

• Flags:
  • -a, --attach: Attach to the agent immediately.
  • -f, --force: Force resume an agent in the error phase. This attempts an in-place restart of a crashed or interrupted session, preserving the prior harness conversation state instead of starting fresh.

scion attach

Connects to the interactive session of a running agent.

When connecting to a Hub behind Google Identity-Aware Proxy (IAP), scion attach automatically attempts to resolve transport-layer authentication (Google OIDC ID tokens) before evaluating the application-level access token gate. If transport auth can be successfully established (e.g., using your local Google Cloud SDK identity or GKE Workload Identity), the application token check is bypassed, enabling seamless attachment in proxy-auth/IAP mode.

Usage: scion attach <agent-name>

• Key Bindings:
  • Ctrl+P, Ctrl+Q: Detach from the session without stopping the agent.

scion message (or msg)

Sends a message to a running agent or user.

Usage: scion message <recipient> <message> [flags]

• Recipients:

  • <agent-name>: Send to an agent (default, same as agent:<name>).
  • agent:<name>: Send to an agent explicitly.
  • user:<name>: Send to a user’s inbox. (Hub mode only)
  • group[a,b,...]: Send to multiple recipients. (Hub mode only)
  • @<agent-name>: Send to an agent’s conversation (preferred).
  • @<email>: Send to a user by email (global DM).
  • conv:<uuid>: Send to a conversation by ID. (Hub mode only)
  • #<thread>: Send to a named thread. (Hub mode only)

• Arguments:

  • <recipient>: The recipient (see above).
  • <message>: The text to send.

• Flags:

  • -i, --interrupt: Interrupt the harness before sending the message.
  • -w, --wake: Resume a suspended agent before delivering the message.
  • --body-file <path>: Read the message body from a file instead of passing it inline. Useful for long messages and scripted workflows. Mutually exclusive with the inline <message> argument.
  • --attach <path>: Attach one or more file paths (repeatable). File paths must be within allowed roots (/workspace or /scion-volumes), where relative paths resolve against /workspace.
    • Constraints: Cannot be combined with --raw, --in, or --at.
    • Requirements: Requires Hub mode (scion hub enable). If run in local mode, the command will fail with an error suggesting you include file contents directly in the message text. If the file is not a regular file (e.g., is a directory) or is outside allowed roots, the command will fail.
  • --cc <agents>: (Deprecated — will be removed.) Carbon copy additional agents. This flag is repeatable and also accepts a comma-separated list of agent names (e.g., --cc dev-agent,qa-agent --cc test-agent). Use group[...] addressing or body @mentions instead.
  • --notify: (Deprecated — use scion notifications subscribe instead.) Get notified when the target agent(s) respond or reach a terminal state after receiving the message.
  • --plain: (Deprecated — will be removed.) Mark for plain-text delivery.
  • --channel <channel>: (Deprecated — use conversation addressing instead.) Target a specific message channel (e.g., telegram, gchat, teams, web).
  • --thread-id <id>: (Deprecated — use conversation addressing instead.) Target a specific thread ID within the channel.
  • --raw: (Deprecated — use scion keys instead.) Send literal bytes via tmux send-keys with no trailing Enter.
  • --in <duration>: (Deprecated — use scion schedule create --in instead.) Schedule message delivery after a duration.
  • --at <time>: (Deprecated — use scion schedule create --at instead.) Schedule message delivery at an absolute time.

• Message Body Formatting: The command delivers the <message> argument verbatim — it performs no escape expansion, no markdown rendering, and no character substitution. Whatever bytes you pass are exactly what the recipient receives.

  To include newlines, use real newlines inside shell quoted strings or heredocs. Do not use JSON-encoded bodies or literal backslash-n (\n) sequences — those will appear as literal characters in the delivered message.

  • Correct (real newlines in a quoted string):

    scion message --non-interactive @reviewer "PR #42 is ready for review.
    
    Branch: fix/auth-bug
    CI: all green"

  • Correct (heredoc for longer messages):

    scion message --non-interactive @reviewer "$(cat <<'EOF'
    PR #42 is ready for review.
    
    Branch: fix/auth-bug
    CI: all green
    EOF
    )"

  • Wrong (JSON-encoded body with literal \n):

    # BAD: literal \n chars appear in the delivered message
    scion message --non-interactive @reviewer "PR #42 is ready for review.\n\nBranch: fix/auth-bug\nCI: all green"

scion broadcast

Sends a message to all running agents in the current project (or across all projects).

Usage: scion broadcast <message> [flags]

This command replaces the removed --broadcast / --all flags on scion message.

scion keys

Sends raw keystrokes to an agent’s terminal via tmux send-keys with no trailing Enter. Supports control keys like arrows and Escape. This command replaces the deprecated --raw flag on scion message.

Usage: scion keys <agent-name> <keys>

scion set-message-mode

Sets the message mode for an agent, controlling which users and agents can send messages to it. Full-role agents can also call this command programmatically.

Usage: scion set-message-mode <agent-name> <mode>

• Arguments:
  • <agent-name>: The target agent.
  • <mode>: One of project (default), branch, lineage, none, or hub.

See Message Authorization & Modes for details on each mode. The hub mode enables cross-project messaging.

scion messages (aliases: msgs, inbox)

Manages bidirectional communication and persistent messages sent by agents to humans.

Usage: scion messages [command] [flags]

• Commands:
  • list (default): View unread messages.
  • read <message-id>: Mark a specific message as read.
  • read-all: Mark all messages as read.
• Flags:
  • --agent <string>: Filter messages by a specific agent.
  • --all: Show all messages, including those already marked as read.

scion conversation (alias: conv)

Manages conversations — the surface-agnostic containers for message threads. Requires Hub mode. Running scion conversation without a subcommand defaults to list.

Conversations are referenced using one of three forms:

• conv:<uuid> — by conversation ID.
• @<agent-name> — resolves the direct conversation with the named agent.
• #<thread-name> — resolves a named group conversation.

Usage: scion conversation [command] [flags]

• Commands:
  • list (default): List conversations you participate in.
  • get <conversation-ref>: Show conversation details.
  • get-message <conversation-ref> <message-id>: Retrieve a single message by its ID from a conversation. Authorization is participant-based — only participants of the conversation can retrieve its messages.
  • messages <conversation-ref>: View messages in a conversation.
  • create <name>: Create a new group conversation.
  • set-default <conversation-ref> <agent-id>: Set the default agent for a conversation.
  • participants <conversation-ref>: List participants in a conversation.
  • join <conversation-ref> <principal-kind> <principal-id>: Add a participant to a conversation.
  • leave <conversation-ref>: Leave a conversation.
  • catch-up <conversation-ref>: Show recent messages in a conversation.
• Flags (on list):
  • --kind <string>: Filter by kind (direct, group).
  • --surface <string>: Filter by surface (native, discord, slack, etc.).
  • --project <string>: Filter by project ID.
  • --limit <int>: Maximum number of conversations to show (default 50).
  • --json: Output in JSON format.
• Flags (on messages):
  • --limit <int>: Maximum number of messages to show (default 25).
  • --before <time>: Show messages before this time (RFC 3339).
  • --after <time>: Show messages after this time (RFC 3339).
  • --json: Output in JSON format.
• Flags (on create):
  • --project <string>: Project ID (defaults to current project).
  • --json: Output in JSON format.
• Flags (on catch-up):
  • --since <duration>: Show messages from this duration ago, e.g. 30m, 2h (default 1h).
  • --json: Output in JSON format.
• Flags (on get-message):
  • --json: Output in JSON format.

scion logs

Displays the logs of an agent.

Usage: scion logs <agent-name> [flags]

• Flags:
  • -f, --follow: Stream logs.

scion list (or ps)

Lists all agents and their status.

Usage: scion list [flags]

• Flags:
  • -a, --all: Show all agents (including stopped ones).
  • -r, --running: Filter for active (running) agents.

scion delete (or rm)

Deletes an agent, removing its container, home directory, and worktree.

Usage: scion delete <agent-name> [flags]

• Flags:
  • -b, --preserve-branch: Preserve the git branch associated with the worktree (default: deleted).
  • --stopped: Delete all agents with stopped containers.

scion sync

Synchronizes the agent workspace between the host and the container.

Usage: scion sync [to|from] <agent-name> [flags]

• Flags:
  • --dry-run: Preview changes without syncing.
  • --exclude <glob>: Exclude files matching the pattern.

scion reset-auth

Injects a fresh Hub token into a running agent’s container and signals it to reload, without restarting the agent. Use this to recover an agent whose token expired and cannot self-refresh (e.g. after a Hub signing-key rotation). Requires a Hub connection. The same action is available as a Reset Auth button in the web UI.

Usage: scion reset-auth <agent-name>

Configuration & Workspace

scion project

Manages the Scion workspace (Project).

• scion project init: Initialize a new project. By default, creates a .scion directory in the current directory or the root of the current git repository.
  • Flags:
    • --global: Initialize the global project in the home directory.
    • --machine: Perform full machine-level setup (seeds harness-configs, templates, settings).
    • --image-registry <string>: Configure the container image registry path (e.g., ghcr.io/myorg).
  • Note: If you are in a git repository, add .scion/agents to your .gitignore to avoid issues with nested git worktrees: echo ".scion/agents" >> .gitignore
  • Hub Integration: If a Hub endpoint is configured, init will prompt to register the new project with the Hub.
• scion project list (alias ls): List all projects known to Scion on this machine, including their type, agent count, status, and workspace path.
• scion project prune: Detect and remove project configurations whose workspace directories no longer exist. This stops any running containers associated with orphaned projects before cleaning up.
• scion project reconnect <new-workspace-path>: Reconnect a moved workspace to its externalized project configuration. This fixes projects that show as “orphaned” after being relocated.
• scion project skills: Manage auto-injected skills for the project.
  • list [project] (alias ls): List auto-injected skills configured for the current project (or a specified project).
  • add [project] <uri>: Add a skill URI to the project’s auto-injected list.
    • Flags: --as <alias> (alias under which to mount the skill), --optional (continue provisioning if resolution fails), --from-directory <url> (discover and batch-add all skills from a GitHub repository directory).
  • remove [project] <id|uri> (aliases rm, delete): Remove an auto-injected skill entry from the project by its ID or full URI.
• scion project hook (alias psh): Manage project-scoped pre-start hooks. These shell scripts run inside the container during agent initialization, and abort agent startup on failure.
  • list [project] (alias ls): List pre-start hooks for a project.
  • show <id-or-slug> [project]: Show details and script content of a pre-start hook.
  • create [project]: Create a new hook (archives the current active hook).
    • Flags: --name (required, human-readable name), --script (required, path to shell script, or - for stdin), --slug (url-safe identifier), --description (optional description).
  • update <id-or-slug> [project]: Update an existing pre-start hook.
    • Flags: --name, --script, --description.
  • activate <id-or-slug> [project]: Mark an archived hook as active (archives any currently active hook).
  • delete <id-or-slug> [project] (alias rm, remove): Delete an archived hook. Active hooks cannot be deleted.
• scion project messaging: Manage cross-project messaging policy for a project.
  • set [project]: Set the inbound messaging policy.
    • Flags: --policy <string> (one of none, members, all), --revision <int> (required, optimistic concurrency revision).
  • get [project]: Show the current messaging policy and revision.

scion user

Manages per-user Hub settings.

• scion user skills: Manage auto-injected skills for your user across all projects.
  • list (alias ls): List your personal auto-injected skills.
  • add <uri>: Add a skill URI to your personal auto-injected list.
    • Flags: --as <alias> (alias under which to mount the skill), --optional (continue provisioning if resolution fails), --from-directory <url> (discover and batch-add all skills from a GitHub repository directory).
  • remove <id|uri> (aliases rm, delete): Remove an auto-injected skill entry from your personal list by its ID or full URI.

scion secret

Manages project-scoped secrets from the host or within an agent container. This command mirrors the sciontool secret commands used in agent containers, using the hubclient Secrets service to operate on the active project.

Unlike scion hub secret (which supports managing secrets at any scope: user, hub, project, or broker), scion secret is streamlined for project-level secrets within your current project context.

• scion secret set KEY VALUE: Store a project-scoped secret in the Hub.
  • If VALUE starts with @, the remainder is treated as a file path. The file contents are read and base64-encoded, and --type defaults to file.
  • Flags:
    • --type <string>: Secret type: environment (default), variable, or file.
    • --target <string>: Injection target path (defaults to key for env, required for file-type secrets).
    • --allow-progeny: Allow child agents (progeny) to inherit this secret.
• scion secret get KEY: Retrieve the metadata of a project-scoped secret. Secret values are never returned to protect security.
• scion secret list: List metadata (key, type, version, updated time) for all project-scoped secrets. Secret values are never returned.

scion clean

Removes the scion project configuration from the current project or global location.

Usage: scion clean [flags]

• Flags:
  • --skip-hub-check: Skip Hub connectivity check before removing.

scion config

View and modify configuration settings.

• list: List all effective settings.
• get <key>: Get a specific configuration value.
• set <key> <value>: Set a configuration value.
• validate: Validate settings files against the schema.
• migrate: Migrate configuration to the latest versioned format.
• dir: Print the path to the active configuration directory.

scion cd-config

Open a new shell in the active Scion configuration directory.

Usage: scion cd-config

scion cd-project

Open a new shell in the active project’s workspace directory.

Usage: scion cd-project

scion cdw

Change directory to the workspace of an agent.

Usage: scion cdw <agent-name>

scion shared-dir

Manages shared directories for agents within a project.

• list: List shared directories in the current project.
• create <name>: Create a new shared directory.
• info <name>: View details about a specific shared directory.
• remove <name>: Remove a shared directory (permanently deletes contents).

Template Management

scion templates

Manages agent templates. scion template (singular) is an accepted alias. Scope defaults to the project; add the root --global flag to target global templates.

• list: List available templates (local, and Hub when connected), grouped by scope.
• show <name>: Show a template’s resolved configuration.
  • Flags: --local (search local only), --hub (search Hub only).
• create <name>: Create a new template (seeded from the default template).
• clone <src> <dest>: Clone an existing template (local or Hub source) to a new local one.
  • Flags: --local, --hub (restrict where the source is searched).
• delete <name> (alias rm): Delete a template.
  • Flags: --local, --hub.
• import <source>: Import agent definitions (Claude/Gemini sub-agents or Scion templates) into your templates directory.
  • Flags: --all (import every discovered agent), -H, --harness <type> (force claude/gemini), --name <name> (rename a single import), --force (overwrite), --dry-run (preview).
• update-default: Update the global default template with the latest from the binary.
  • Flags:
    • --force: Overwrite the existing default template if it already exists.

Hub-only commands (require an enabled Hub):

• sync [template] (alias push): Create or update a template in the Hub; only changed files are uploaded. Use --all to sync every local template, or --name <name> to sync under a different Hub name.
• pull <name>: Download a template from the Hub to the local filesystem. Use --to <path> for a custom destination.
• status: Show the sync status of templates relative to the Hub.

See Templates & Roles for the full guide.

Skill Bank

scion skills

Manages skills in the Hub skill bank — reusable, versioned instruction snippets referenced by URI (scion skill, singular, is an alias). See Skills — Authoring & Publishing for the full guide. All subcommands except create require a Hub connection.

• list: List available skills.
  • Flags: --scope <core|global|project|user>, --search <text>, --tags <a,b> (comma-separated, AND semantics).
• show <name-or-id>: Show a skill’s details and versions.
• create <name>: Scaffold a new local skill directory with a starter SKILL.md (local-only; does not publish).
• publish <path>: Publish a local skill directory to the Hub. Limits: 50 files, 10 MB/file, 50 MB total.
  • Flags: --version <semver> (required), --scope <core|global|project|user> (default global for new skills), --skill-id <id>.
• versions <name-or-id>: List all versions of a skill.
• resolve <uri>: Resolve a skill URI to a concrete version, content hash, and file manifest.
• deprecate <name-or-id>: Mark a published version as deprecated.
  • Flags: --version <version> (required), --message <text> (required), --replacement <uri>.
• delete <name-or-id> (alias rm): Soft-delete a skill (archived, retained for history).

scion skills registries

Manages external skill registries for federation. Admin operations.

• list: List configured registries.
• add <name>: Register an external skill registry.
  • Flags: --endpoint <url> (required, HTTPS), --trust <trusted|pinned> (default pinned), --type <hub|gcp> (default hub), --description <text>, --auth-token <token>, --resolve-path <path>.
• show <name-or-id>: Show registry details.
• update <name-or-id>: Update a registry. Flags: --endpoint, --trust, --status <active|disabled>, --description, --auth-token, --resolve-path (only changed flags are applied).
• remove <name-or-id>: Remove a registry.
• pin <name-or-id> <skill-uri>: Pin a content hash for a pinned-trust registry. Flag: --hash <sha256:...> (required).

Harness Configuration

scion harness-config (alias hc)

Manages harness-config bundles — the named, versioned definitions of each harness (config, image, capabilities, auth, and supporting files). See Harness-Specific Settings for the full lifecycle.

• list: List local harness-configs. Flags: --hub (also include Hub-registered configs).
• show <name>: Show config details (local path/image, or Hub ID, image status, and source URL).
• install <source>: Install a config from a GitHub URL, local path, rclone URI, or archive. Flags: --name (override derived name), --force (overwrite existing), --global (register at global scope on the Hub).
• update [name]: Re-import (refresh) a config from its stored source URL. Flags: --url <url> (override/set the stored source URL for one config), --all (re-import every config that has a stored source URL). --url and --all are mutually exclusive; requires a Hub connection.
• sync <name> (alias push): Upload a local config to the Hub (changed files only). Flags: --name (publish under a different Hub name).
• pull <name>: Download a config from the Hub. Flags: --to <path> (destination; defaults to the global dir).
• reset <name>: Restore a config to the binary’s embedded defaults.
• upgrade [name]: Add missing support files and metadata without clobbering user values. Flags: --dry-run, --activate-script, --force. With no name, upgrades all configs in the global directory.
• delete <name>: Delete a config from the Hub (does not remove local files). The web UI additionally offers an “Also delete stored files” option.

Hub Integration

scion hub

Manages connection to and interaction with a Scion Hub. Authentication lives under scion hub auth (there is no top-level scion auth command).

• scion hub auth: Manage Hub authentication.
  • login: Authenticate with Hub server (opens a browser; supports --no-browser for device flow and --provider github).
  • logout: Clear stored credentials.
• scion hub token: Manage user access tokens (scoped, revocable bearer tokens for CI/CD and automation).
  • create: Create a new token.
    • Flags:
      • --project <string>: Project ID or name to scope the token to (required).
      • --name <string>: Token name/label (required).
      • --scopes <scopes>: Scopes to grant (required). This flag is repeatable and also accepts a comma-separated list of scopes (e.g., --scopes agent:read,agent:create --scopes agent:start). Strict empty-value validation is enforced.
      • --expires <duration>: Expiry duration (e.g., 30d, 90d, 1y, default: 90d).
  • list: List your access tokens.
  • revoke <token-id>: Revoke a token (remains visible in listings as revoked).
  • delete <token-id>: Permanently delete a token.
• scion hub status: Show the current Hub connection status.
• scion hub notifications: Deprecated. This command has been moved to the top-level scion notifications command group.
• scion hub link: Link the current local project to the Hub.
• scion hub unlink: Unlink the current project from the Hub locally.
• scion hub projects: List all projects registered on the Hub.
• scion hub brokers: List all runtime brokers registered on the Hub.
• scion hub secret: Manage write-only secrets on the Hub.
  • set <key> <value>: Set a secret (supports --allow-progeny for user-scoped secrets).
  • get [key]: Get secret metadata.
  • clear <key>: Remove a secret.
• scion hub env: Manage environment variables on the Hub.
  • set <key>=<value>: Set a variable.
  • get [key]: Get variable values.
  • clear <key>: Remove a variable.
• scion hub project create <git-url>: Create a project from a remote git repository.
  • Flags: --slug, --name, --branch, --visibility, --json
• scion hub hook (alias psh): Manage hub-scoped (baseline) pre-start hooks. Requires administrator privileges.
  • list (alias ls): List hub-scoped pre-start hooks.
  • show <id-or-slug>: Show details and script content of a hub-scoped hook.
  • create: Create a new hook (archives the current active hook).
    • Flags: --name (required, human-readable name), --script (required, path to shell script, or - for stdin), --slug (url-safe identifier), --description (optional description).
  • update <id-or-slug>: Update an existing hook.
    • Flags: --name, --script, --description.
  • activate <id-or-slug>: Mark an archived hook as active (archives any currently active hub-scoped hook).
  • delete <id-or-slug> (alias rm, remove): Delete an archived hook. Active hooks cannot be deleted.
• scion hub messaging: Manage hub-wide cross-project messaging settings. Requires administrator privileges.
  • set: Set hub-wide messaging settings.
    • Flags: --cross-project-enabled <bool> (enable or disable cross-project messaging), --revision <int> (required, optimistic concurrency revision).
  • get: Show the current hub-wide messaging settings and revision.

Notification Management

scion notifications

Manages notifications and notification subscriptions. Requires Hub mode.

• scion notifications: List your recent unacknowledged notifications.
  • Flags: --all (include acknowledged notifications), --json (format output as JSON).
• scion notifications ack [id]: Acknowledge one or all notifications.
  • Flags: --all (acknowledge all unacknowledged notifications).
• scion notifications subscribe: Subscribe to notifications for a specific agent or all agents in a project.
  • Flags:
    • --agent <name-or-id>: Subscribe to specific agent.
    • --project <name>: Specify project (inferred from context if omitted).
    • --triggers <triggers>: Trigger activities to subscribe to. This flag is repeatable and also accepts a comma-separated list of triggers (e.g., --triggers COMPLETED,WAITING_FOR_INPUT --triggers LIMITS_EXCEEDED). Default: COMPLETED,WAITING_FOR_INPUT,LIMITS_EXCEEDED. Strict empty-value validation is enforced.
• scion notifications unsubscribe <id>: Remove a subscription.
  • Flags: --all (remove all subscriptions in the project), --project <name>.
• scion notifications update <id>: Update a subscription’s trigger activities.
  • Flags:
    • --triggers <triggers>: Trigger activities to update (required). This flag is repeatable and also accepts a comma-separated list of triggers (e.g., --triggers COMPLETED,WAITING_FOR_INPUT --triggers LIMITS_EXCEEDED). Strict empty-value validation is enforced.
• scion notifications subscriptions: List your active notification subscriptions.
  • Flags: --project <name> (filter by project), --json (format output as JSON).

Infrastructure

scion broker

Manages the local host as a Runtime Broker.

• scion broker status: Show status of the local broker server.
• scion broker start: Start the broker server as a background daemon.
• scion broker stop: Stop the broker daemon.
• scion broker register: Register this host as a Runtime Broker with the Hub.
• scion broker deregister: Remove this broker’s registration from the Hub.
• scion broker provide: Add this broker as a provider for a project.
• scion broker withdraw: Remove this broker as a provider from a project.

scion server

Manages Scion server components (Hub and Broker).

• scion server start: Start one or more server components.
  • Flags:
    • --enable-hub: Enable the Hub server component.
    • --enable-runtime-broker: Enable the Runtime Broker component.
    • --port <int>: Port to listen on.
    • --db <string>: Database driver/connection.
    • --dev-auth: Enable dev-auth authentication.
    • --admin-emails <emails>: Email addresses to auto-promote to the administrator role. This flag is repeatable and also accepts a comma-separated list (e.g. --admin-emails admin1@example.com,admin2@example.com --admin-emails admin3@example.com). Strict empty-value validation is enforced.
• scion server backfill: Scan historical messages that predate the conversation model and assign them to conversations based on their thread, sender, and recipient metadata.
  • Safety Default (Dry-Run): By default, the command runs in DRY-RUN mode — scanning and reporting what would change without modifying the database. You must explicitly pass --execute to apply changes.
  • Idempotency: The backfill is idempotent: messages already attributed to a conversation are skipped, making re-running entirely safe.
  • Compound-Cursor Resumability (DEF-81): Supports resuming interrupted runs via --checkpoint. The resume checkpoint uses a compound (created, id) keyset cursor (instead of a strictly-greater-than timestamp) to guarantee zero permanent row loss on resume, even for messages with identical timestamps.
  • Flags:
    • --execute: Apply changes (default: dry-run, safe).
    • --project <string>: Scope backfill to a specific project ID (default: all).
    • --batch-size <int>: Number of messages to process per batch (default: 100).
    • --checkpoint <string>: Resume from this pagination cursor (project-scoped).
    • --db <string>: Database DSN (overrides configuration/environment DSN).

Administration

scion admin

Administrative operations for emergency recovery scenarios. These commands connect directly to the database, bypassing the running server. They are intended for break-glass situations where normal admin access has been lost.

scion admin promote

Promotes an existing user to the admin role by connecting directly to the database, bypassing the running Hub server. This is a break-glass recovery command for situations where all admin users have been removed or an organization has lost admin access.

The target user must already exist in the database — this command does not create new users.

Usage: scion admin promote [flags]

• Flags:
  • --email <string>: Email address of the user to promote (required).
  • --db <string>: Database URL or path (overrides the config-derived connection). Accepts Postgres connection strings (postgres://...) or SQLite file paths.
  • --config <string>: Path to server configuration file (defaults to the standard settings.yaml resolution).

Examples:

# Promote using the default config-derived database connection
scion admin promote --email user@example.com

# Promote with an explicit Postgres database URL
scion admin promote --email user@example.com --db postgres://user:pass@host:5432/db

# Promote using a specific config file
scion admin promote --email user@example.com --config /path/to/server.yaml

Break-glass only

This command modifies the database directly. Use it only when normal admin access through the Hub API or Web Dashboard is unavailable. Under normal operation, manage admin roles via the Web Dashboard Users list or the admin_emails server setting.

Miscellaneous

scion doctor

Runs host-side diagnostics: checks Git, tmux, the active container runtime, and runtime-specific health (Docker/Podman daemon, or Kubernetes cluster/namespace/RBAC/CSI access). Supports --format json.

Usage: scion doctor [flags]

In-container diagnostics

A separate sciontool doctor command runs inside an agent container and diagnoses the agent’s own health — environment variables, Hub token (presence/format/expiry), Hub reachability, token refresh, the GCP metadata server, and the GitHub App token. See Harness Authentication.

scion whoami

Prints identity details of the current agent container or system user.

• Outside an agent container: Gracefully falls back to the system whoami command (e.g., printing the current operating system user).
• Inside an agent container: Prints the agent’s identity. By default, it prints the agent’s slug in plain text.

Usage: scion whoami [flags]

• Flags:
  • --full: Enriches the output with live metadata from the Hub.
    • When run in plain text, prints a human-readable multi-line summary of both local environment settings and live Hub details (e.g., agent phase, activity, etc.).
    • When run with --format json, includes both Tier 1 and Tier 2 fields in the JSON object.
    • If the Hub is unreachable, the command gracefully degrades to returning environment-only details, printing a warning to stderr.
  • --format json (persistent global flag): Returns a structured JSON output representing the agent’s identity configuration and state.

Output Details (--format json)

The command populates a structured JSON schema divided into two latency tiers:

Tier 1 (Always populated, zero latency, derived from container environment variables)

• slug: The agent’s slug identifier (falls back to its name if slug is absent).
• name: The agent’s display name.
• id: The unique agent UUID.
• project / projectId: The assigned project’s name and ID.
• template: The name of the template used to spawn the agent.
• harness: The underlying agent harness (e.g., codex, etc.).
• model: The model used by the agent.
• creator: The identity of the agent’s creator.
• brokerName / brokerId: The running broker’s name and ID.
• cliMode: The active CLI mode.
• hubEndpoint: The endpoint URL of the connecting Hub.
• hubUrl: The reconstructed direct URL pointing to the agent’s resource page on the Hub ({hubEndpoint}/agents/{id}).

Tier 2 (Enriched, requires --full flag and Hub connectivity)

• phase: The current lifecycle phase of the agent (e.g., running, suspended, error).
• activity: The current runtime activity status of the agent (e.g., thinking, stalled, offline).
• labels: Metadata key-value pairs assigned to the agent.
• annotations: System key-value pairs attached to the agent.
• ancestry: A lineage array representing the agent’s parent/child spawn relationships.
• taskSummary: A brief summary of active task execution.

scion version

Prints the Scion version information and optionally checks for available updates.

Usage: scion version [flags]

• Flags:
  • --check: Query the release manifest (LATEST.json) for available updates across release channels (stable, preview, nightly). Outputs update availability in plain text by default, or structured JSON when combined with --format json.