The Octopus CLI can be used to run runbooks that have already been created.
Runs a Runbook.
Usage: octo run-runbook [<options>]
Where [<options>] is any of:
Run Runbook:
--project=VALUE Name or ID of the project that contains the
Runbook. This is required.
--runbook=VALUE Name or ID of the runbook. If the name is
supplied, the project parameter must also be
specified.
--environment=VALUE Name or ID of the environment to run in, e.g .,
'Production' or 'Environments-1'; specify this
argument multiple times to run in multiple
environments.
--snapshot=VALUE [Optional] Name or ID of the snapshot to run. If
not supplied, the command will attempt to use
the published snapshot.
--forcePackageDownload [Optional] Whether to force downloading of
already installed packages (flag, default false).
--guidedFailure=VALUE [Optional] Whether to use Guided Failure mode.
(True or False. If not specified, will use
default setting from environment)
--specificMachines=VALUE
[Optional] A comma-separated list of machine
names to target in the specified environment/s.
If not specified all machines in the environment
will be considered.
--excludeMachines=VALUE
[Optional] A comma-separated list of machine
names to exclude in the specified environment/s.
If not specified all machines in the environment
will be considered.
--tenant=VALUE [Optional] Run a runbook on the tenant with this
name or ID; specify this argument multiple times
to add multiple tenants or use `*` wildcard to
deploy to all tenants who are ready for this
release (according to lifecycle).
--tenantTag=VALUE [Optional] Run a runbook on the tenants matching
this tag; specify this argument multiple times
to build a query/filter with multiple tags, just
like you can in the user interface.
--skip=VALUE [Optional] Skip a step by name
--runAt=VALUE [Optional] Time at which runbook run should
start (scheduled run), specified as any valid
DateTimeOffset format, and assuming the time
zone is the current local time zone.
--noRunAfter=VALUE [Optional] Time at which scheduled runbook run
should expire, specified as any valid
DateTimeOffset format, and assuming the time
zone is the current local time zone.
-v, --variable=VALUE [Optional] Specifies the value for a prompted
variable in the format Name:Value. For JSON
values, embedded quotation marks should be
escaped with a backslash.
--waitForRun [Optional] Whether to wait synchronously for
deployment to finish.
--progress [Optional] Show progress of the runbook run
--runTimeout=VALUE [Optional] Specifies maximum time (time span
format) that the console session will wait for
the runbook run to finish (default 00:10:00).
This will not stop the run. Requires --
waitForRun parameter to be set.
--cancelOnTimeout [Optional] Whether to cancel the runbook run if
the run timeout is reached (flag, default false).
--runCheckSleepCycle=VALUE
[Optional] Specifies how much time (time span
format) should elapse between runbook run status
checks (default 00:00:10)
--noRawLog [Optional] Don't print the raw log of failed
tasks
--rawLogFile=VALUE [Optional] Redirect the raw log of failed tasks
to a file
Common options:
--help [Optional] Print help for a command.
--helpOutputFormat=VALUE
[Optional] Output format for help, valid options
are Default or Json
--outputFormat=VALUE [Optional] Output format, valid options are
Default or Json
--server=VALUE [Optional] The base URL for your Octopus Server,
e.g., 'https://octopus.example.com/'. This URL
can also be set in the OCTOPUS_CLI_SERVER
environment variable.
--apiKey=VALUE [Optional] Your API key. Get this from the user
profile page. You must provide an apiKey or
username and password. If the guest account is
enabled, a key of API-GUEST can be used. This
key can also be set in the OCTOPUS_CLI_API_KEY
environment variable.
--user=VALUE [Optional] Username to use when authenticating
with the server. You must provide an apiKey or
username and password. This Username can also be
set in the OCTOPUS_CLI_USERNAME environment
variable.
--pass=VALUE [Optional] Password to use when authenticating
with the server. This Password can also be set
in the OCTOPUS_CLI_PASSWORD environment variable.
--configFile=VALUE [Optional] Text file of default values, with one
'key = value' per line.
--debug [Optional] Enable debug logging.
--ignoreSslErrors [Optional] Set this flag if your Octopus Server
uses HTTPS but the certificate is not trusted on
this machine. Any certificate errors will be
ignored. WARNING: this option may create a
security vulnerability.
--enableServiceMessages
[Optional] Enable TeamCity or Team Foundation
Build service messages when logging.
--timeout=VALUE [Optional] Timeout in seconds for network
operations. Default is 600.
--proxy=VALUE [Optional] The URL of the proxy to use, e.g.,
'https://proxy.example.com'.
--proxyUser=VALUE [Optional] The username for the proxy.
--proxyPass=VALUE [Optional] The password for the proxy. If both
the username and password are omitted and
proxyAddress is specified, the default
credentials are used.
--space=VALUE [Optional] The name or ID of a space within
which this command will be executed. The default
space will be used if it is omitted.
--logLevel=VALUE [Optional] The log level. Valid options are
verbose, debug, information, warning, error and
fatal. Defaults to 'debug'.Basic Examples
This runs a runbook using the published snapshot:
octo run-runbook --runbook="Hello World" \
--project="Smurfs" \
--environment="Test" \
--server="https://your-octopus-url" \
--apiKey="API-YOUR-KEY"This runs a runbook using a specific snapshot (e.g., Snapshot XXXXX):
octo run-runbook --runbook="Hello World" \
--project="Smurfs" \
--environment="Test" \
--snapshot="Snapshot XXXXX" \
--server="https://your-octopus-url" \
--apiKey="API-YOUR-KEY"To specify multiple environments, you can use the following:
octo run-runbook --runbook="Hello World" \
--project="Smurfs" \
--environment="Test" \
--environment="Dev" \
--server="https://your-octopus-url" \
--apiKey="API-YOUR-KEY"You can run a runbook on ALL tenants in an environment by using the --tenant=* argument.
Learn more
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023