Configuration

SwitchTender is one binary with subcommands. This page lists every command, flag, and environment variable.

Licensed features

Almost everything on this page runs on Community, which needs no license. Six features are licensed, and separately an install is capped on how many approval policies it holds at once. A flag or request that turns on a licensed feature is refused outright rather than quietly ignored, so an install never believes it has a control it does not have.

license status prints the tier this install runs and when a license lapses. Tiers and prices are at https://switchtender.com/pricing.

Environment variables

init

Bootstraps a new deployment. It creates the database and the first admin account, writes an environment file, and optionally a systemd unit. Run it once, then start serve.

The admin password comes from SWITCHTENDER_ADMIN_PASSWORD, or is generated and printed once when that variable is unset.

serve

Runs the HTTP API, the in-process executor, the scheduler, the retention sweeper, and the web UI.

Retention windows accept a whole number of days with a d suffix, such as 30d, or Go duration syntax such as 720h.

AI providers

The advisory AI features run against one provider, chosen with --ai-provider: ollama for a local model, or anthropic and openai for a cloud model with SWITCHTENDER_AI_KEY. The provider is off until set, and no feature ever executes anything the provider suggests.

Cloud models see automation content: commands, playbook names, failed-run logs, and host drift. Because that content is security-adjacent, a model with strict safety classifiers can decline a benign request as a false positive. When the Anthropic model is a Fable or Mythos model, SwitchTender opts into server-side fallbacks, so a declined request is retried on claude-opus-4-8 in the same call and the feature keeps working. A Fable model also requires that the account keep 30-day data retention, or the API rejects every request.

desktop

Runs SwitchTender as a local desktop application. It serves on a private loopback port, stores its data in a per-user directory, and opens the web UI in the default browser. It takes no flags. Set SWITCHTENDER_DESKTOP_NO_BROWSER to skip opening a browser. See Desktop for packaging a macOS app or a Windows installer.

worker

Leases pending runs from the shared store and executes them. Point it and a server at the same database and they compete for work. Or start it with --server and it leases runs from the control node over the mesh relay, with no database access of its own.

token

Manages API tokens. A public bind on an empty database mints an initial admin token at startup.

• token new --name <label> [--user <username>] [--ttl <duration>] [--agent] mints a token, printed once. A zero TTL never expires.
• --user binds the token to an account, and the token carries that account's role. A token minted without --user is unscoped and acts as admin, so bind every token you hand to a person, a service, or an AI agent. See running an agent.
• --agent marks the token as held by an AI agent rather than a person. It caps the token at operator whatever role its account holds, so an agent can launch and propose work but can never manage identity, access, or secrets, and can never approve its own held run. Every action it takes is recorded in the chain as actor_type: agent with the account it acts for beside it, which is what actor_kind: agent policy rules match on. It requires --user, so the chain always records the human the agent acts for; without one the command refuses. Mint every agent token with it: a token without --agent is indistinguishable from a person's in the record.
• token list lists tokens without their secrets.
• token revoke <id> deletes a token.

All token subcommands take --db and the global --pretty flag for indented JSON.

user

Manages accounts with roles: admin, operator, and viewer.

• user new <username> --role <role> creates an account. The password comes from SWITCHTENDER_PASSWORD or a prompt, never an argument.
• user list lists accounts.
• user delete <id> deletes an account. Its tokens stop working.

All user subcommands take --db.

license

Shows or installs this install's license. No license is Community, which is complete in itself. What each tier covers is listed at https://switchtender.com/pricing.

• license status shows the tier this install runs and when a license lapses.
• license install <file> verifies a license file and installs it beside the database.

A license is read from SWITCHTENDER_LICENSE, or from switchtender-license.json in the same directory as the database. A license this install cannot parse or that has lapsed reads as Community rather than failing the server, so an expiry never takes an install down.

assess

Reports what an automation export holds and what governing it would change, without writing anything and without a database. It reads an export the same way import does, then grades every template it found through the same risk and reversibility graders the product uses at run time, so a number in an assessment cannot disagree with what a run would later say.

switchtender assess awx awx-export.json
switchtender assess chef chef-nodes.json

Formats are awx, semaphore, chef, and puppet. An AWX-format export also covers Ansible Automation Platform, Tower, and Ascender.

The output has three parts: what is in the export, what survives the move, and what changes about how it is governed. The third part names the templates that cannot be undone, the ones carrying a destructive signal, the credentials more than one template shares, and the templates targeting no stored inventory.

Grades are a floor rather than a measurement. An Ansible template keeps its work in a playbook, and at assessment time that playbook is in a repository nothing has fetched, so reading one can only ever raise a grade. The report says how many templates that applies to rather than leaving the numbers looking more settled than they are.

import

Migrates from AWX, Semaphore, Chef, Puppet, Rundeck, Jenkins, or cron. Which objects each one carries across is in what each source brings over.

• import awx <export.json> [--apply] brings projects, inventories static and dynamic, credential shells, job templates and workflows, surveys, and schedules.
• import semaphore <export.json> [--apply] brings the same kinds from a Semaphore export, apart from the dynamic inventory sources AWX alone carries.
• import chef <nodes.json> [--apply] brings one inventory of the fleet: every node a host, grouped by its chef_environment and by every role[...] in its run list, carrying the ohai facts that identify a machine, with ipaddress also set as ansible_host. Accepts an array of node documents, a single node, or an object keyed by node name. Cookbooks and recipes are not imported and the recipes seen are named in the report.
• import puppet <nodes.json|facts.json|nodes.txt> [--apply] brings one inventory of the fleet, grouped by environment, from a PuppetDB nodes query, a PuppetDB facts query, or the plain certname list puppet node list prints. Deactivated and expired nodes are left out and counted. Manifests and modules are not imported.
• import rundeck <jobs.yaml|project-archive.zip> [--inventory <name>] [--apply] brings templates, surveys, and schedules from either a job export or a project archive, told apart by content. An archive brings one project as well, but only when its source control configuration names a repository this can reach. Neither artifact carries a node definition, so no inventory is imported from either and --inventory names the hosts its jobs target.
• import jenkins <JENKINS_HOME|jobs-dir|config.xml> [--inventory <name>] [--apply] brings templates, surveys, and schedules from freestyle jobs. Jenkins picks an agent by label, so --inventory names the machines.
• import cron <crontab-file> [--inventory <name>] [--system] [--apply] brings schedules alone, one per crontab line, each carrying its own one-step bash pipeline rather than a template. --system parses the six-field /etc/crontab form, whose user column sits before the command. That step runs on the SwitchTender host, not on the machine the crontab came from.

All five take --db for the target database. Without --apply the command only reports what it would create. Rundeck, Jenkins, and cron import no credentials, so a job that needed a login needs one built by hand afterward.

audit

Audit trail tools.

• audit bundle emits the chain as a signed LoomSeal bundle. Anyone verifies it offline with the open loomseal verifier, or in a browser, without trusting the server that produced it.
• audit anchor has a public timestamp authority sign the current head, so a chain that has lost its tail no longer reaches its anchor.
• audit receipt <seq:link> redeems a receipt the server issued, proving that entry is still in the chain.
• audit report renders the period's change register as a self-contained HTML evidence report.
• audit run <id> emits one run's evidence dossier as a self-contained HTML document.

receipt

Writes a signed receipt for one finished run, which a third party verifies offline with verify. A receipt is the chain segment from the request that created the run through the entry recording what it did, signed with this install's key and carrying any anchors that fix its position.

Publish the key fingerprint the command prints so a verifier can pin it.

verify

Verifies a receipt written by receipt. It trusts nothing this server says: it recomputes every chain link from the receipt's own claims, checks the signature covers the exact bytes, and confirms any anchors name an entry the receipt holds. It reads only the file, reaches no database and no network, and does not run the server, so a relying party can check a receipt on a machine that has never seen this install.

switchtender verify run.receipt --pubkey sha256:...

Pass --pubkey with the fingerprint the producer published to tie the result to a key obtained out of band. Without it the receipt is checked against the key it names, which proves it was not altered but not who signed it.

witness

Watches a server's span beat feed from outside it. A chain proves what it holds was not altered, but not that nothing was removed from the end, because the process running the chain also decides what gets written down. A witness on another machine remembers what the feed served, keeps that memory in a signed checkpoint, and raises a finding when a beat goes missing, an already-witnessed beat comes back rewritten, or the head regresses. Run it where the server's operator has no hand.

• witness serve watches many servers from one process and answers auditors with countersigned attestations.
• witness verify-attestation verifies an attestation offline against a pinned witness key.

mcp

Serves the Model Context Protocol over stdio, so an agent can list templates, propose a run, and read what happened. Every tool call is an ordinary authenticated API request carrying the token given here, so it passes the same authorization, the same approval policy, and the same fail-closed audit append as a request from a person. See Agents.

export SWITCHTENDER_MCP_TOKEN=swt_...
switchtender mcp --server https://switchtender.internal

The token is read from SWITCHTENDER_MCP_TOKEN, falling back to SWITCHTENDER_TOKEN. Prefer the environment variable to a flag, whose value is visible in the host's process list. The command refuses to start on an admin token. There is deliberately no approve tool, so an agent cannot release its own work, and no credential, account, token, grant, or policy tool, so it cannot widen its own reach.

demo

Seeds a fresh database with sample data and real runs, then serves it read-only, so a public instance is safe to expose. It needs ansible on the PATH to run the sample playbooks.

Seeding runs real playbooks and takes a couple of minutes, which is a visible gap if a public demo reseeds in place. The two flags split that work in half so it can happen off to the side:

switchtender demo --db next.db --seed-only     # build the next database, serving continues
mv next.db demo.db                             # swap it in
switchtender demo --db demo.db --no-seed       # serves the prepared data in under a second

A host wired this way reseeds without a visible outage, since the running instance keeps answering the whole time the replacement is being built.

examples

Seeds a handful of starter templates, so a first launch works on the spot rather than opening on an empty list. They use the Bash tool and print or read something local, needing no project, inventory, or credential. Delete them once you have your own.

Run it against the same database serve uses. It skips a template whose name is already present, so it is safe to run twice. Takes --db.

backup

Writes an encrypted, portable backup of the control-plane configuration and secrets. The whole file is sealed with the deployment encryption key, so it stays confidential and tamper-evident, and it restores into either the SQLite or the PostgreSQL backend. See Backup and restore.

Run history and the audit chain are not included. The audit chain has its own signed export, through audit bundle.

restore

Reads a backup and upserts its objects into the store by id. It needs the same encryption key the backup was written with, and it never deletes objects absent from the file.

version

Prints the SwitchTender version.

help and completion

Both are the standard Cobra built-ins. help prints usage for any command, and completion emits a shell completion script for bash, zsh, fish, or PowerShell.

Output flags

JSON goes to stdout compact by default. Three commands take --pretty to indent it; it is not a global flag, so passing it elsewhere is an error rather than a no-op.

Separation between organizations is opt-in

Organizations, teams, and grants exist, but with --strict-grants off an object nobody has granted falls back to the caller's global role. On that default any operator may use any project, inventory, or credential in the install, whichever organization it belongs to. That is deliberate: a small team should not have to grant every object before anything works, and an upgrade should not lock people out of what they were already using.

It does mean an install with several organizations on it is not separated until --strict-grants is on. If you are running work for more than one team, more than one customer, or anything where one group must not reach another's credentials, turn it on and grant deliberately. Objects created before you do carry no grants, so plan to assign them.

Directory sign-in and existing accounts

An account records what created it: an administrator, or the directory that provisioned it. A directory identity signs in to an account only when that account is its own, so an identity provider asserting the username of a local administrator is refused rather than handed that administrator's account and role.

This matters most when the username does not come from a stable subject. With --jwt-username-claim email or a SAML username attribute pointing at an email, against an issuer that lets a user set their own address, matching on username alone was account takeover. OIDC has always refused the equivalent when the provider does not vouch for the address.

An account created before this was recorded carries no source, so it cannot be told apart from a local one of the same name. Those are still signed in to, because refusing them would lock out every directory user on upgrade, and each is logged so an administrator can set the source and remove the ambiguity.

Confining relay workers to their queues

A relay worker runs in a segment the control node cannot reach, which means the least trusted machine in the estate holds a worker token. With a single --worker-token, that machine may name any queue it likes and lease from it, so a compromised host in a DMZ can take a production run and execute it with production credentials.

--worker-pools binds each token to the queues it may serve. The file stores the SHA-256 of each token, never the token itself, the same way a webhook secret is stored:

workers:
  - name: dmz
    token_sha256: 9f2c...           # sha256 of that pool's bearer token
    queues: [dmz]
  - name: production
    token_sha256: 41ab...
    queues: [prod, canary]

A pool that declares no queues may lease from all of them, which is the single-token shape stated out loud. A pool that declares queues is refused anything else, including the default queue when it names none, so confinement cannot be escaped by omission.

Generate a digest with printf %s "$TOKEN" | shasum -a 256. A malformed file stops the server rather than falling back to no confinement, because an install that believes it is segmented and is not is worse than one that refuses to start.

That confines the lease side. The submit side is confined by granting the queue, which is a grantable object named queue:<name>:

curl -X POST localhost:8080/v1/grants \
  -H "Authorization: Bearer $ST_TOKEN" \
  -d '{"subject": "team_sre", "object": "queue:prod", "access": "use"}'

A queue nobody has granted follows the same rule every other object does: the global role decides, unless --strict-grants is on, in which case an ungranted queue is refused. Granting a queue makes it access-controlled, so only the subjects named may route work to it. The grant is checked wherever a queue is chosen: on a run, on a template, on an inventory, and at launch against the template's own queue.

An install that has not turned strict grants on can gate a queue with a rule instead, since a policy matches on queue:

policies:
  - name: hold anything headed for production
    queue: prod
    require_distinct_approver: true

A policy with queue holds only what is routed to that queue, and a run on a named queue executes only when a worker serving that queue claims it; the control node's own runner takes unqueued runs alone. On an install without relay workers, a queued run therefore waits as pending indefinitely, even after approval. To gate runs the server itself executes, write the policy without queue.

What a relay worker writes into the audit trail

A relay worker runs where the control node cannot see it, so two moments are recorded: the run leaving for that machine, and the outcome coming back.

RELAY  /relay/claim/run_4f21a9      worker:build-dmz-01
RELAY  /relay/finished/run_4f21a9/succeeded

Captured output, structured events, per-host and per-task summaries, and heartbeats are not recorded. They are the content and liveness of a run that is already stored on the run itself, they arrive several times a second, and writing each into a hash chain would drown the record it exists to make readable.

This append does not fail closed, unlike every mutation through the API. Refusing a worker's report because the audit store is unhealthy does not un-finish the run; it loses the outcome of work that already ran on real hosts. A failure to record is logged loudly instead.