Command reference

Every command, subcommand and flag the semaphore binary accepts, in the order semaphore help walks the tree. Use it to confirm a flag name or a default; the pages next to it explain what the commands are for.

Every command reads the same configuration as the server, so point it at the right configuration file with --config when you run more than one instance on a host. See CLI for the lookup order.

Global flags

These are accepted by every command.

Flag	Type	Default	Description
--config	string	—	Configuration file path
--debug-filter	string	—	Debug namespace filter (only with DEBUG level), e.g. 'runner,task_' or ',-db'
--log-level	string	—	Log level: DEBUG, INFO, WARN, ERROR, FATAL, PANIC
--no-config	bool	—	Don't use configuration file

semaphore migrate

Execute migrations

semaphore migrate

Flag	Type	Default	Description
--apply-to	string	—	Apply to specific version
--err-log-size	int	0	Error log size
--merge-existing-users	bool	—	Reuse existing users matched by username instead of failing on conflict
--skip-task-output	bool	—	Skip task output importing during migration
--undo-to	string	—	Undo to specific version

semaphore projects

Manage projects

semaphore projects

Aliases: project.

Subcommand	Purpose
semaphore projects export	Export project backup
semaphore projects import	Import project(s)

semaphore projects export

Export project backup

semaphore projects export

Flag	Type	Default	Description
--file	string	—	Output file path (default: stdout)
--project-id	int	0	Project ID to export
--project-name	string	—	Project name to export

semaphore projects import

Import project(s)

semaphore projects import

Flag	Type	Default	Description
--dir	string	—	Directory path with project backups to import
--file	string	—	Backup file path to import
--project-name	string	—	Override project name (only valid with --file)

semaphore runner

Run in runner mode

semaphore runner

Subcommand	Purpose
semaphore runner register	Register runner on the server
semaphore runner setup	Perform interactive setup
semaphore runner start	Run in runner mode
semaphore runner unregister	Unregister runner from the server

semaphore runner register

Register runner on the server

semaphore runner register

Flag	Type	Default	Description
--enabled	bool	true	Enable or disable the runner on the server
--name	string	—	Runner name to register with
--project-id	int	0	Project ID for project-level runner (global runner if not provided)
--registration-token-file	string	—	Read registration token from a file
--stdin-registration-token	bool	—	Read registration token from stdin
--tags	stringSlice	—	Runner tags (comma-separated or repeat the flag)
--webhook	string	—	Runner webhook URL

semaphore runner setup

Perform interactive setup

semaphore runner setup

semaphore runner start

Run in runner mode

semaphore runner start

Flag	Type	Default	Description
--auto-register	bool	—	Register new runner if not registered
--register	bool	—	Alias of --auto-register

semaphore runner unregister

Unregister runner from the server

semaphore runner unregister

semaphore server

Run in server mode

semaphore server

Aliases: service.

semaphore setup

Perform interactive setup

semaphore setup

semaphore users

Manage users

semaphore users

Aliases: user.

Subcommand	Purpose
semaphore users add	Add new user
semaphore users change-by-email	Change user found by email
semaphore users change-by-login	Change user found by login
semaphore users delete	Remove existing user
semaphore users get	Show user's data
semaphore users list	Print all users
semaphore users token	Manage user API tokens
semaphore users totp	Manage TOTP verification

semaphore users add

Add new user

semaphore users add

Flag	Type	Default	Description
--admin	bool	—	Mark new user as admin
--email	string	—	New user email
--external	bool	—	Mark new user as external (LDAP or OIDC user)
--login	string	—	New user login
--name	string	—	New user name
--password	string	—	New user password

semaphore users change-by-email

Change user found by email

semaphore users change-by-email

Flag	Type	Default	Description
--admin	bool	—	Mark user as admin
--email	string	—	User's new email
--login	string	—	User login
--name	string	—	User's new name
--password	string	—	User's new password

semaphore users change-by-login

Change user found by login

semaphore users change-by-login

Flag	Type	Default	Description
--admin	bool	—	Mark user as admin
--email	string	—	User's new email
--login	string	—	User login
--name	string	—	User's new name
--password	string	—	User's new password

semaphore users delete

Remove existing user

semaphore users delete

Flag	Type	Default	Description
--email	string	—	Email of the user you want to delete
--login	string	—	Login of the user you want to delete

semaphore users get

Show user's data

semaphore users get

Flag	Type	Default	Description
--email	string	—	Email of the user you want to see
--login	string	—	Login of the user you want to see

semaphore users list

Print all users

semaphore users list

semaphore users token

Manage user API tokens

semaphore users token

Subcommand	Purpose
semaphore users token create	Create new API token
semaphore users token list	List user API tokens

semaphore users token create

Create new API token

semaphore users token create

Flag	Type	Default	Description
--login	string	—	Login of the token owner
--name	string	—	Token name
--ttl	string	—	Token lifetime (e.g. 1h, 30m, 24h). Token never expires if omitted

semaphore users token list

List user API tokens

semaphore users token list

Flag	Type	Default	Description
--login	string	—	Login of the token owner

semaphore users totp

Manage TOTP verification

semaphore users totp

Subcommand	Purpose
semaphore users totp disable	Disable TOTP verification
semaphore users totp enable	Enable TOTP verification
semaphore users totp show	Show TOTP details

semaphore users totp disable

Disable TOTP verification

semaphore users totp disable

Flag	Type	Default	Description
--login	string	—	User login

semaphore users totp enable

Enable TOTP verification

semaphore users totp enable

Flag	Type	Default	Description
--login	string	—	User login

semaphore users totp show

Show TOTP details

semaphore users totp show

Flag	Type	Default	Description
--login	string	—	User login

semaphore vaults

Manage access keys and other secrets

semaphore vaults

Aliases: vault.

Subcommand	Purpose
semaphore vaults check	Report which key id encrypts each stored secret
semaphore vaults rekey	Re-encrypt all stored secrets under the active encryption key

semaphore vaults check

Read-only. Reports, per key id, how many locally stored Access Key secrets and the JWT signing key it encrypts, plus the JWT option's status. Use it after vault rekey to confirm a retired key is safe to remove: a key with zero references can be deleted from the keyset. Rows whose key id is missing from the keyset are flagged and cause a non-zero exit.

semaphore vaults check

semaphore vaults rekey

Re-encrypt all locally stored secrets (access keys and the JWT signing key) under the active key, stamping its key id into each value. Zero-downtime rotation: 1. Add a new key to the keyset (a file in keys_folder, or a keys: entry) and point active.access_key (or access_key_file) at it; reload applies it within keys_poll_interval, or send kill -HUP <pid>. 2. Run vault rekey to re-encrypt existing data to the new key. 3. Run vault check; once the old key shows 0 rows it is safe to remove. Legacy: vault rekey --old-key <old-key> decrypts un-prefixed data with an explicit old key.

semaphore vaults rekey

Flag	Type	Default	Description
--backup	string	—	Write a backup of current access key ciphertexts to this file before re-encrypting
--old-key	string	—	Explicit old encryption key (legacy single-key migration; not needed when the old key is configured as a secondary)
--rollback	string	—	Restore access key ciphertexts from a backup file instead of re-encrypting

semaphore version

Print the version of Semaphore

semaphore version