Octopus Deploy Documentation

The Octopus Command Line (CLI)

Last updated

The Octopus CLI is a command line tool that builds on top of the Octopus Deploy REST API. With the Octopus CLI you can package your applications for deployment as either Zip or NuGet packages, and manage your environments, deployments, channels, projects, and workers.

The Octopus CLI can be used on Windows, Mac, Linux, Docker, and as a .NET Core global tool. For installation options and direct downloads, visit Download Octopus CLI.

Commands

octo supports the following commands:

General Usage

All commands take the form of:

octo <command> [<options>]

You can see a list of commands using:

octo help

And you can get help for a specific command using:

octo help <command>
octo <command> --help

Arguments are not case sensitive and can take the following forms:

--project OctoFX                # Space between argument name and value
--project=OctoFX                # Equal sign between argument name and value
--project "OctoFX Web Site"     # Argument values with spaces need to be quoted
"--project=OctoFX Web Site"     # If using equals, quote both the name and value, not just the value

All commands require you to pass the URL of the Octopus Server's API endpoint, and an API key which is used to authenticate you.

octo ... --server http://your-octopus-server/ --apiKey API-ABCDEF123456

Most commands also support JSON formatted output.

Create an API key
Learn about how to create an API key.

The Octopus CLI is built and maintained by the Octopus Deploy team, but it is also open source. You can view the Octopus CLI project on GitHub, which leans heavily on the Octopus Clients library.

The server URL, API key, username and password can be set as the environment variables OCTOPUS_CLI_SERVER, OCTOPUS_CLI_API_KEY, OCTOPUS_CLI_USERNAME and OCTOPUS_CLI_PASSWORD respectively. Values set via command line arguments take precedence over environment variables.

Tab completion for commands and options

Tab completion is available for the following shell environments: powershell, pwsh (PowerShell Core), bash & zsh. This feature requires that octo or Octo is available from your $PATH, which is the default state if installed via a package manager or Chocolatey. If you've manually installed the CLI, please ensure your $PATH is also updated if you wish to use this feature. This is an optional feature that requires additional installation steps on a per user basis, since this feature relies on built-in shell auto completion facilities.

Additional installation steps for tab completion.

  1. Check that octo is available on your path:
which octo

This should return a valid location on your path like /usr/bin/octo.

  1. Install tab completion scripts into your profile, choosing from powershell, pwsh, bash or zsh:
octo install-autocomplete --shell zsh

If you're using PowerShell on Windows use powershell if you're using PowerShell Core on Windows, Mac or Linux, use pwsh.

You can review changes to your profile without writing to disk by using the --dryRun option

octo install-autocomplete --shell powershell --dryRun
  1. Either restart your shell environment or 'dot source' your profile:
. ~/.bashrc
. ~/.zshrc
. $PROFILE
  1. You can now discover sub-commands by typing octo [searchterm] and hitting the [tab] key. If you don't provide a search term, the full list of available sub-commands will be shown.

animation showing the tab completion feature in Zsh to list all environments in the default space

Need support? We're here to help.