{"id":21313951,"url":"https://github.com/octopusdeploy/cli","last_synced_at":"2025-10-29T17:05:13.752Z","repository":{"id":46558255,"uuid":"515418692","full_name":"OctopusDeploy/cli","owner":"OctopusDeploy","description":"| Public |  Next Generation of the Octopus CLI :octopus:","archived":false,"fork":false,"pushed_at":"2025-10-28T23:07:47.000Z","size":2387,"stargazers_count":41,"open_issues_count":54,"forks_count":14,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-10-29T01:08:32.792Z","etag":null,"topics":["public"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OctopusDeploy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-07-19T03:17:30.000Z","updated_at":"2025-10-21T06:30:48.000Z","dependencies_parsed_at":"2023-10-03T13:04:53.226Z","dependency_job_id":"26797df5-0dfd-40c3-b0ce-c2893918b5c7","html_url":"https://github.com/OctopusDeploy/cli","commit_stats":{"total_commits":267,"total_committers":20,"mean_commits":13.35,"dds":0.6704119850187267,"last_synced_commit":"eb6ee729a45624a9cf5dca0a04f2987d4994b314"},"previous_names":[],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/OctopusDeploy/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OctopusDeploy","download_url":"https://codeload.github.com/OctopusDeploy/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctopusDeploy%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281571637,"owners_count":26524052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["public"],"created_at":"2024-11-21T18:09:27.097Z","updated_at":"2025-10-29T17:05:13.721Z","avatar_url":"https://github.com/OctopusDeploy.png","language":"Go","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"go-octopusdeploy Logo\" src=\"logo.png\" width=\"256\" /\u003e\n  \u003ch3 align=\"center\"\u003ecli\u003c/h3\u003e\n  \u003cp align=\"center\"\u003eCommand Line Interface for \u003ca href=\"https://octopus.com/\"\u003eOctopus Deploy\u003c/a\u003e 🐙\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/OctopusDeploy/cli/releases/latest\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/github/v/release/OctopusDeploy/cli.svg?logo=github\u0026style=flat-square\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/badge/github.com/OctopusDeploy/cli\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/OctopusDeploy/cli\" alt=\"Go Report\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Installation\n\n#### Linux \u0026 macOS - CURL script\n\nIn your Terminal, run the following command:\n\n```shell\ncurl -L https://github.com/OctopusDeploy/cli/raw/main/scripts/install.sh | bash\n```\n\nThis will install Octopus CLI in `/usr/local/bin`. Depending on the permission of `/usr/local/bin`, you may need to provide your sudo password.\n\nIf you would like to install to a different location, set the `INSTALL_PATH` variable accordingly:\n\n```shell\ncurl -L https://github.com/OctopusDeploy/cli/raw/main/scripts/install.sh | INSTALL_PATH=$HOME/bin bash\n```\n\nYou can also install a specific version by providing the `VERSION` variable:\n\n```shell\ncurl -L https://github.com/OctopusDeploy/cli/raw/main/scripts/install.sh | VERSION=v0.4.0 bash\n```\n\n#### Windows - MSI file\n\nNavigate to latest release on the [GitHub releases page](https://github.com/OctopusDeploy/cli/releases) and expand the **Assets** list.\n\nDownload and run the file `octopus_[version]_Windows_x86_64.msi`\n\n*Note:* At this time, the installer is x64 only. If you are using Windows on ARM, download the manual archive instead.\n\n#### Windows - Chocolatey\n\n```shell\nchoco install octopus-cli\n```\n\n*Note:* At this time, the chocolatey package is x64 only. If you are using Windows on ARM, download the manual archive instead.\n\n#### Windows - winget\n\n```shell\nwinget install OctopusDeploy.Cli\n```\n\n*Note:* At this time, the winget package is x64 only. If you are using Windows on ARM, download the manual archive instead.\n\n#### macOS - Homebrew\n\n```shell\nbrew install octopusdeploy/taps/octopus-cli\n```\n\nThe Homebrew package has native support for macOS Intel and Apple Silicon\n\n#### Linux (debian/ubuntu based distributions)\n\n```shell\nsudo apt update \u0026\u0026 sudo apt install --no-install-recommends gnupg curl ca-certificates apt-transport-https \u0026\u0026 \\\nsudo install -m 0755 -d /etc/apt/keyrings \u0026\u0026 \\\ncurl -fsSL https://apt.octopus.com/public.key | sudo gpg --dearmor -o /etc/apt/keyrings/octopus.gpg \u0026\u0026 \\\nsudo chmod a+r /etc/apt/keyrings/octopus.gpg \u0026\u0026 \\\necho \\\n  \"deb [arch=\"$(dpkg --print-architecture)\" signed-by=/etc/apt/keyrings/octopus.gpg] https://apt.octopus.com/ \\\n  stable main\" | \\\n  sudo tee /etc/apt/sources.list.d/octopus.list \u003e /dev/null \u0026\u0026 \\\nsudo apt update \u0026\u0026 sudo apt install octopus-cli\n\n# for legacy Ubuntu/Debian (\u003c 18.04) use\n# sudo apt update \u0026\u0026 sudo apt install --no-install-recommends gnupg curl ca-certificates apt-transport-https \u0026\u0026 \\\n# curl -sSfL https://apt.octopus.com/public.key | sudo apt-key add - \u0026\u0026 \\\n# sudo sh -c \"echo deb https://apt.octopus.com/ stable main \u003e /etc/apt/sources.list.d/octopus.com.list\" \u0026\u0026 \\\n# sudo apt update \u0026\u0026 sudo apt install octopus-cli\n```\n\n#### Linux (redhat/fedora based distributions)\n\n```shell\nsudo curl -sSfL https://rpm.octopus.com/octopuscli.repo -o /etc/yum.repos.d/octopuscli.repo \u0026\u0026 \\\nsudo yum install octopus-cli\n```\n\n#### Any Platform - Manual\n\nDownload and extract the archive file for your platform from the latest release on the [GitHub releases page](https://github.com/OctopusDeploy/cli/releases).\n\n- macOS (Apple Silicon): `octopus_[version]_macOS_arm64.tar.gz`\n- macOS (Intel): `octopus_[version]_macOS_x86_64.tar.gz`\n- Windows (x64): `octopus_[version]_Windows_x86_64.zip`\n- Linux (x64): `octopus_[version]_Linux_x86_64.tar.gz`\n\nThe archive file simply contains a compressed version of the `octopus` binary. If you would like to add it to your `PATH` then you must do this yourself.\n\n#### Any platform - go install\n\nIf you have the go development tools installed, you can run\n\n```shell\ngo install github.com/OctopusDeploy/cli/cmd/octopus@latest\n```\n\nThis will download the latest public release of the CLI from our GitHub repository, compile it for your platform/architecture, and install the binary in your GOPATH\n\n## Getting Started\n\nTo get started with the Octopus CLI, login to your Octopus Server using the following command:\n\n```\noctopus login\n```\n\nThis command will walk you through setting the Octopus Server URL, creating an API key (if necessary) and configuring the CLI for use.\n\n### Open ID Connect\n\nIn automation scenarios such as CI servers, the login command can be used to authenticate using OpenID Connect (OIDC). This involves exchanging an ID token from an OIDC provider (such as GitHub or GitLab) for an Octopus access token.\n\nTo login using OIDC, use the following command:\n\n```\noctopus login --server {OctopusServerUrl} --service-account-id {ServiceAccountId} --id-token {IdTokenFromProvider}\n```\n\nFor example:\n\n```\noctopus login --server https://my.octopus.app --service-account-id 834a7275-b5b8-42a1-8b36-14f11c8eb55e --id-token eyJhbGciOiJQUzI1NiIs...\n```\n\nThis command will perform the token exchange and configure the CLI for use.\n\nSee the [documentation on OpenID Connect for more information](https://oc.to/ServiceAccountOidcIdentities)\n\n## Overview\n\nThis project aims to create a new CLI (written in Go) for communicating with the Octopus Deploy Server.\n\nIt does **not** seek to be a drop-in replacement for the existing CLI which is written in C# using .NET.\nhttps://github.com/OctopusDeploy/OctopusCLI\n\n### Differences from the .NET CLI (octo)\n\nThe new CLI restructures the command line to be more consistent, and fit with convention\nacross other popular CLI apps. It is built on the popular and widely-used [Cobra](https://github.com/spf13/cobra)\ncommand line processing library.\n\nThe new CLI does not intend to replace all features that were supported by the .NET CLI.\n\n#### Examples:\n\n**.NET CLI**\n\n    octo list-releases\n    octo create-release\n\n**Go CLI**\n\n    octopus release list\n    octopus release create\n\nThe new CLI supports an \"interactive\" mode, where it will prompt for input where\nparameters are not fully specified on the command line.\n\n## Documentation\n\n- [cli](https://octopus.com/docs/octopus-rest-api/cli)\n\n## 🤝 Contributions\n\nContributions are welcome! :heart: Please read our [Contributing Guide](CONTRIBUTING.md) for information about how to get involved in this project.\n\n# Developer Guide\n\n## Getting Started\n\nFirst, ensure that you have [Go](https://go.dev/) installed, and available in your `PATH`.\nTo verify this, open a new terminal window and type `go version`. You should see something similar to `go version go1.18.4 windows/amd64`\n\nNext, clone this git repository\n\nNext, open the directory you cloned into, navigate into the `cmd/octopus` directory, and type `go build .`\n\n```shell\ncd \u003cyour-local-development-dir\u003e\ngit clone https://github.com/OctopusDeploy/cli\ncd cli\ncd cmd/octopus\ngo build .\n```\n\nIf successful, the go compiler does not output anything. You should now have an `octopus` binary\n(`octopus.exe` on windows) in your current directory.\n\n**Makefile**\n\nIf you are using a sytem that has `make` installed, then you can also simpl run `make` in the cli root folder.\nThe default action for the `Makefile` is to run `go build`, as above.\n\n## Running the CLI\n\nThe CLI needs to authenticate with the octopus server. \n\nYou can configure this using the `octopus login` command from the [Getting Started guide above](#getting-started) or by setting environment variables.\n\n**macOS/Linux:**\n\n```shell\nexport OCTOPUS_URL=\"http://localhost:8050\" # replace with your octopus URL\nexport OCTOPUS_API_KEY=\"API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\" # replace with your API key\n./octopus space list # should list all the spaces\n```\n\n**Windows (powershell):**\n\n```shell\n$env:OCTOPUS_URL=\"http://localhost:8050\" # replace with your octopus URL\n$env:OCTOPUS_API_KEY=\"API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\" # replace with your API key\n./octopus.exe space list # should list all the spaces\n```\n\n**Windows (cmd):**\n\n```shell\nset OCTOPUS_URL=\"http://localhost:8050\" # replace with your octopus URL\nset OCTOPUS_API_KEY=\"API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\" # replace with your API key\noctopus.exe space list # should list all the spaces\n```\n\n### go-octopusdeploy library\n\nThe CLI depends heavily on the [go-octopusdeploy](https://github.com/OctopusDeploy/go-octopusdeploy) library, which manages\ncommunication with the Octopus Server via its JSON API.\n\n## Code structure\n\nThe CLI follows standard go language conventions for packages, and fits around the package structures set out by the\nCobra library for commands.\n\nA rough overview is as follows:\n\n```shell\ncmd/\n   octopus/  # Contains the octopus binary\n\npkg/\n   apiclient/ # Utility code used to manage authentication/connection to the octopus server\n   cmd/ # contains sub-packages for each cobra command\n      account/ # contains commands related to accounts\n      environment/ # contains commands related to environments\n      ... # more commands\n  constants/ # constant values to avoid duplicated strings, ints, etc\n  errors/ # internal error objects\n  executor/ # See 'architecture' below\n  factory/ # \"service locator\" object used by commands to locate shared services\n  output/ # internal utilities which help formatting output\n  question/ # See 'architecture' below\n\ntestutil/ # internal utility code used by both unit and integration tests\nintegrationtest/ # Contains integration tests\n```\n\n### Testing\n\nUnit tests for packages follow go language conventions, and is located next to the code it is testing.\n\n```shell\npkg/\n  question/\n    input.go\n    input_test.go # unit tests for the code contained in input.go\n```\n\nThe easiest way to run the tests is to `cd pkg` and run `go test ./...`.\nWe find `gotestsum` provides a nice wrapper around the underlying go test functionality, which you may also prefer.\n\n### Integration Tests\n\nIntegration tests live outside the pkg structure and operate outside the app.\nThey launch the CLI as a seperate process, and interact with it using stdout and stderr.\n\n**Important:** Integration tests assume that an Octopus Deploy server is running and accessible.\nBefore running the integration tests you must set the following environment variables, or the tests will fail.\n\n```shell\nOCTOPUS_TEST_URL=\"http://localhost:8050\" # replace with your octopus URL\nOCTOPUS_TEST_APIKEY: \"API-XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\" # replace with your API key\n```\n\n**Important:** Integration tests require an admin-level API key.\n\n**Important:** Integration tests assume an empty Octopus Server database.\nIf your server contains existing data, the tests may fail, and they may modify or delete any existing data.\n\nThe easiest way to run the tests is to `cd integrationtest` and run `go test ./...` or `gotestsum`\n\n## Guidance and Example of how to create and test new commands\n\nImagine that the CLI did not contain an \"account create\" command, and we wished to add one.\n\nWe would go about it as follows:\n\n#### 1. Create packages and files for the command, linking in with Cobra.\n\nWe would make a `/cmd/account/create` directory, and within it put `create.go`\n\nWe would implement a `func NewCmdCreate(f factory.Factory) *cobra.Command` function which set up\nthe command structure, parameters, flags, etc, and link it in with the parent code in `account.go`\n\nExample:\n\n```go\nfunc NewCmdCreate(f factory.Factory) *cobra.Command {\n\tcmd := \u0026cobra.Command{\n\t\tUse:   \"create\",\n\t\tShort: \"Create an account\",\n\t\tLong:  \"Create an account in Octopus Deploy\",\n\t\tExample: heredoc.Docf(\"$ %s account create\", constants.ExecutableName),\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\treturn nil // TODO\n\t\t},\n\t}\n\tcmd.Flags().StringP(\"name\", \"n\", \"\", \"name for the item\")\n\tcmd.Flags().StringP(\"description\", \"d\", \"\", \"description for the item\")\n\treturn cmd\n}\n```\n\n#### 2. Create a `Task` which encapsulates the command arguments\n\nin the `executor` package, create a new string constant, and struct to carry the options for your command\n\n```go\nconst TaskTypeCreateAccount = \"createAccount\"\n\ntype TaskOptionsCreateAccount struct {\n    Name           string   // REQUIRED.\n    Description    string   // optional\n}\n```\n\nBack in your `cmd` file, write some code which maps values from the command flags, and puts them into the `Task` structure,\nthen submit it to the excutor which will do the work when you call `ProcessTasks`\n\n```go\nRunE: func(cmd *cobra.Command, args []string) error {\n    name := cmd.Flags().GetString(\"name\")\n    description := cmd.Flags().GetString(\"description\")\n\n    task := executor.NewTask(executor.TaskTypeCreateAccount, executor.TaskOptionsCreateAccount{\n        Name:        name,\n        Description: description,\n        // etc\n    })\n\n    executor.ProcessTasks(f, []executor.Task{ task })\n}\n```\n\n#### 3. Extend the `executor` to handle your new task\n\nUpdate the code in ProcessTasks to match your new task identifier string, and write a new helper function\nto do the work (sending data to the octopus server, etc.)\n\nAt this point you should have a functioning command which works in automation mode.\n\n#### 4. Write unit tests to ensure your command works as expected\n\nThe unit tests for [release list](https://github.com/OctopusDeploy/cli/blob/main/pkg/cmd/release/list/list_test.go) are a reasonable place to start with as an example.\n\n#### 5. Implement interactive mode\n\nReturn back to your new command's go file (`account/create.go` in this example)\n\nAt a high level, you should create a function which encapsulates the interactive question/answer session, and returns\nyour `TaskOptions` structure, which you then pass to `ProcessTasks`\n\nYou should pass a reference to the `Ask` func, which allows you to mock out the `Survey` library, and then you should\nwrite a series of unit tests which ensure that the question/answer session works correctly.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopusdeploy%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctopusdeploy%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctopusdeploy%2Fcli/lists"}