uselagoon / lagoon-cli

A CLI for Lagoon - Docker Build and Deploy System for Kubernetes

Lagoon CLI

This is a CLI for interacting with a Lagoon instance. By default, it is configured to work against Amazee.io instances.

If you run the CLI in a directory that has a valid .lagoon.yml and docker-compose.yml that references your project in lagoon, then you don't need to specify your project name on the command line as the CLI can read these files to determine the project. You can still define a project name though if you want to target a different project.

Install

The preferred method is installation via Homebrew.

brew tap uselagoon/lagoon-cli
brew install lagoon

Alternatively, you may install by downloading one of the pre-compiled binaries from the releases page

If you are building from source, see the Build section below

Usage

Once installed, to use the Lagoon CLI, run the following command

lagoon <command>

Commands

For the full list of commands see the docs for Lagoon CLI

Building

Requirements

Install Go - https://go.dev/doc/install

You also need mockgen, it can be installed using the following command once Go is installed.

go install go.uber.org/mock/[email protected]

Note: You should make sure you have your GOPATH configured and in your path, see https://pkg.go.dev/cmd/go#hdr-GOPATH_environment_variable

Run tests

make test

Build locally

You can compile the binary and load it into your GOPATH bin directory using the following.

make build

Alternatively, these will compile a binary inside a builds directory in this repository, you can place them wherever you wish.

make build-linux
#macos
make build-darwin
make build-darwin-arm64

Build using Docker

You can build lagoon-cli without installing go by running the docker-build make command. This will use the Dockerfile.build to build the cli inside of a docker container, then copy the binaries into the builds/ directory once complete

make build-docker-darwin
make build-docker-linux

Run all

make all #locally
make all-docker-linux
make all-docker-darwin

Install

make ARTIFACT_DESTINATION=/usr/local/bin install-linux
make ARTIFACT_DESTINATION=/usr/local/bin install-darwin

Notes

Versions can also be defined, and the binaries will be version tagged

make VERSION=v0.0.1 ...

Acknowledgements

Matt Glaman - Initial conception and development - Thanks Matt!

lagoon-cli's Issues

"Dry run" mode

Is your feature request related to a problem? Please describe.
I sometimes want to inspect the GraphQL query generated by the lagoon tool to ensure it's doing what I want, or providing all the fields that I would like, and that they are populated in the way I expect.

Describe the solution you'd like
It would be great to add a global flag -n/--dry-run, which just prints the GraphQL query JSON that would be sent to the server, to STDOUT instead.

Describe alternatives you've considered
Inspecting the source code.

Additional context
This feature request is modelled after the make -n flag.

There is some functionality overlap with the --debug flag, not sure the best way to resolve that. Although maybe --debug addresses a different use-case?

Confusing docs

Is your feature request related to a problem? Please describe.
Docs lack usage examples and lack links to related lagoon docs. There are many examples of different commands that do the same thing.

These 3 docs seem to cover the same operation but none say the difference between the 3 commands, which one should be used, no links to lagoon docs about project notifications, no examples of how to use:

• https://amazeeio.github.io/lagoon-cli/commands/lagoon_add_project-slack/
• https://amazeeio.github.io/lagoon-cli/commands/lagoon_add_slack/
• https://amazeeio.github.io/lagoon-cli/commands/lagoon_add/

Check for updates

It'd be great if there was a check every 24hrs (in reality if more than 24hrs have passed since last check), and some prompt was shown to notify of the existence of a newer version.

Here's what ddev does for example: https://github.com/drud/ddev/blob/master/pkg/ddevapp/ddevapp.go#L752

Retrieve an environment's hits

Example GraphQL:

query {
 environmentByOpenshiftProjectName(openshiftProjectName: "contribkanban-master") {
   hitsMonth(month: "2019-04") {
     total
   }
 }
}

Example run:

lagoon environment hits contribkanban master
``

Ideally later on we could load `.lagoon.yml` and the current Git branch.

Missing license, use MIT

ANSI-color output

Do we want ANSI-color output in the CLI?
I don't really think it is required, but happy to discuss it.
Just returning the data makes more sense to me

Misleading error message for laggon add user-group

Describe the bug
The error message is misleading when omitting the group flag for adding a user to a user-group.

To Reproduce
Steps to reproduce the behavior:

1. run lagoon add user-group -E [email protected] -R developer
2. Error message: Error: Must define an email address

Expected behavior
The error message should mention the missing group parameter, e.g. Error: missing group parameter

Reports feature

Description

It would be great to be able to bake in certain pre-canned reports into the CLI and just dump out the results there (e.g. in a CLI table).

Describe the solution you'd like

e.g.

• Top HTTP 404s in the last 24 hours
• Top IPs in the last 24 hours

etc.

Describe alternatives you've considered

Additional context

This will enable the logs backend to be more flexible on implementation. It also will prevent people from having to learn Elastic Search syntax.

Remove redundant options from commands that do not need them

Is your feature request related to a problem? Please describe.

At the moment, there is no way to hide options for commands that do not use them. This in turn leads to confusion, as the command can choose to completely ignore the options you supplied.

Describe the solution you'd like

Add a way for commands to explicitly declare their options, and remove the ones that are not needed in the --help docs for the command in question.

Support command passthrough when using ssh command

Is your feature request related to a problem? Please describe.
When running lagoon ssh it would be nice to be able to pass in a command to run too

Describe the solution you'd like
Being able to pass a command flag that contains the command, or pass in a script and run it on the remote

lagoon ssh -c "ps"
# or
lagoon ssh < my-script.sh

unify notifications list, add email and teams

Is your feature request related to a problem? Please describe.
Currently I need to run two commands to see all the rocketchat and/or slack notifications associated with a project. With the addition of Microsoft Teams and email notifications, this would then require me running 4 commands to see all the notifications.

Describe the solution you'd like
I should be able to run a simple command like lagoon list notifications -p project-name and get a list of all the notifications of a project, regardless of type.

Provide `latest` as a binary on releases

Is your feature request related to a problem? Please describe.
For situations where the lagoon-cli needs to be downloaded in a script, a way to download latest would be handy.

Describe the solution you'd like
Included a -latest binary to download (linux is most desired currently)

Incorrect docs for deploy command

Describe the bug
Using osx lagoon 0.3.0 (installed with homebrew)

Docs describe lagoon deploy [project name] [branch name] [flags]

Actual syntax is
lagoon deploy branch -p myproject -b dev

To Reproduce
Steps to reproduce the behavior:

1. run lagoon deploy myproject dev as described in docs, fails

Desktop (please complete the following information):

• OS: OSX
• Version 0.3.0

Show something useful when failing to ssh into a project/environment

lagoon ssh -p education-sa -e master
panic: Failed to dial: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain
goroutine 1 [running]:
github.com/amazeeio/lagoon-cli/lagoon/ssh.InteractiveSSH(0xc000141b80, 0x0, 0x0, 0x0, 0x0, 0xc000141bb0)
	/go/src/github.com/amazeeio/lagoon-cli/lagoon/ssh/main.go:17 +0x90a
github.com/amazeeio/lagoon-cli/cmd.glob..func48(0x1a6b280, 0xc0000def80, 0x0, 0x4)
	/go/src/github.com/amazeeio/lagoon-cli/cmd/ssh.go:58 +0x76b
github.com/spf13/cobra.(*Command).execute(0x1a6b280, 0xc0000deec0, 0x4, 0x4, 0x1a6b280, 0xc0000deec0)
	/go/pkg/mod/github.com/spf13/[email protected]/command.go:830 +0x2ae
github.com/spf13/cobra.(*Command).ExecuteC(0x1a6ab00, 0x0, 0x0, 0x14d0b23)
	/go/pkg/mod/github.com/spf13/[email protected]/command.go:914 +0x2fc
github.com/spf13/cobra.(*Command).Execute(...)
	/go/pkg/mod/github.com/spf13/[email protected]/command.go:864
github.com/amazeeio/lagoon-cli/cmd.Execute()
	/go/src/github.com/amazeeio/lagoon-cli/cmd/root.go:61 +0x42
main.main()
	/go/src/github.com/amazeeio/lagoon-cli/main.go:8 +0x20

It was that the project name was incorrect after all, but the above errors lead me to believe that there was something wrong with the authentication. It could be somethings like "no such project" or "no such environment" (suggestions of close matches would be a plus 🙂😉)

Add Slack notifications

See the following mutations

• addNotificationSlack(input: AddNotificationSlackInput!): NotificationSlack
• updateNotificationSlack(input: UpdateNotificationSlackInput!): NotificationSlack
• deleteNotificationSlack(input: DeleteNotificationSlackInput!): String
• deleteAllNotificationSlacks: String

And the NotificationSlack schema

lagoon deploy results improvement

Is your feature request related to a problem? Please describe.
running the lagoon deploy command says success immediately without knowing the results of the deployment

Describe the solution you'd like
I would like to watch the deployment logs (the same that are viewable in lagoon UI) live as they are happening. Maybe a --watch flag?

Additional context
I ran a deployment with the cli and it said success. The deployment failed however.

Onboarding

Is your feature request related to a problem? Please describe.
When onboarding customers or projects, it would be good to be able to provide a file that describes how the customer/project should be configured

Describe the solution you'd like
I think something like this might work well

groups:
  - name: example-com
users:
  - user:
      email: [email protected]
      sshkey: ~/usera.pub
    groups:
      - name: example-com
        role: owner
  - user:
      email: [email protected]
      sshkey: ~/userb.pub
    groups:
      - name: example-com
        role: developer
projects:
  - name: example-com
    giturl: [email protected]:example/example-com.git
    openshift: 2
    branches: "master|develop|staging"
    productionenvironment: master
    groups:
      - example-com

Then a lagoon import -I /path/to/file would start it off

SSH helper

Problem : connecting to a Lagoon environment via SSH requires a difficult to remember series of SSH parameters and hostnames/ports

Solution : Have Lagoon CLI generate and/or execute the necessary SSH connection string

Provide command to launch Kibana

Remembering things is hard. A command should launch the browser for reviewing logs in Kibana.

https://lagoon.readthedocs.io/en/latest/using_lagoon/logging/

List environment variables for a project

Would be nice to know if the environment variables have been modified too, and when (and by whom).

Custom tasks

Is your feature request related to a problem? Please describe.
The ability to run my own tasks.

Describe the solution you'd like
Being able to run a command like cat myscript.sh | lagoon task custom -n "my task"

Additional context
Currently running a custom task is done with a mutation like the following

mutation addTask  {
  addTask(input:{
    environment: 1234
    command:"drush status drupal-version --format=list"
    execute:true
    name:"my task"
    service:"cli"
  }) {
    id
  }
}

Environment promote command

Is your feature request related to a problem? Please describe.
Being able to run deployEnvironmentPromote mutations

Describe the solution you'd like
lagoon promote -p <project> -s <source> -d <dest>

Add verbosity option to all commands

Would be nice to be able to -vvv or similar to dump the full graphQL commands being run, or any other APIs. API tokens should be redacted from display.

lagoon add project doesn't show option for openshift setting

Describe the bug
Help doesn't output openshift flag to set it

To Reproduce
Steps to reproduce the behavior:

1. lagoon add project
2. See lack of openshift option

Expected behavior
lagoon add project

  -a, --autoIdle int                   Auto idle setting of the project
  -b, --branches string                Which branches should be deployed
  -g, --gitUrl string                  GitURL of the project
  -h, --help                           help for project
  -j, --json string                    JSON string to patch
  -S, --openshift int                  Reference to OpenShift Object this Project should be deployed to
  -I, --privateKey string              Private key to use for the project
  -E, --productionEnvironment string   Which environment(the name) should be marked as the production environment
  -m, --pullrequests string            Which Pull Requests should be deployed
  -C, --storageCalc int                Should storage for this environment be calculated
  -s, --subfolder string               Set if the .lagoon.yml should be found in a subfolder Usefull if you have multiple Lagoon projects per Git Repository```

**Desktop (please complete the following information):**
 - OS: Ubuntu 18.04
 - Version: 0.7.0

Update environment variable for a project

Would be nice to be able to either add or update an environment variable depending if it exists already.

Adding a confirmation would be great.

Perhaps run the list command after success.

List an environment's deployments

Implement `whoami`

Is your feature request related to a problem? Please describe.
Feature Request

Describe the solution you'd like
People might have different user accounts on Lagoon so having an lagoon whoami will help them understand with which user account they are currently logged in

When deleting things, display more information about it, prior to the confirmation

Currently when you delete a project there is a confirmation, but no additional information is presented to enable you to make this choice

$ lagoon delete project --project reports
Deleting reports
✔ Yes
Result: success

Describe the solution you'd like
Perhaps a simple confirmation message like:

$ lagoon delete project --project reports
You are attempting to delete project 'reports' ID 10665, with git URL '[email protected]/blah.git', are you sure?

Additional context
The idea here is to prevent people from deleting the wrong thing.

Delete user's SSH key

It would be nice to be able to remove a user's SSH key. You can add one with the CLI, just not remove one.

Describe the solution you'd like

lagoon delete user-sshkey -E [email protected] -n oldKeyName

There already is a GraphQL API mutation in the code

func (api *Interface) DeleteSSHKey(sshKey DeleteSSHKey) ([]byte, error) {

Test slack integration

testing, ignore

New command to deploy PR environments

Is your feature request related to a problem? Please describe.

At the moment you can deploy branches and not pull requests, it would be great if Lagoon CLI was able to deploy both.

Describe the solution you'd like

Something like

lagoon deploy pr -p project -b pr-17

Add and Update Users and Groups

Is your feature request related to a problem? Please describe.
Unable to add or update users or groups

Describe the solution you'd like
The ability to add, update, and list groups and users

Look at getting lagoon-cli into homebrew

It would be good to have this in homebrew once binaries are released

Specify a config file, or cluster to use directly from the command line

Is your feature request related to a problem? Please describe.
When working with the CLI in an automation space, being able to define a specific config file or cluster options directly when running commands

Describe the solution you'd like
Be able to either specify the path to a custom config file

lagoon --config-file /path/to/config.yml list projects

or the main config options for api/ssh access, which will ignore any config files

lagoon --graphql https://api.example.com/graphql \
  --token "ey...xyz" \
  --port 2020 \
  --hostname ssh.example.com \
  list projects

Adding a ssh-key for a user results in access denied

Describe the bug
When trying to add a ssh-key do an existing user the command returns the following error-message:

Error: graphql: Unauthorized: You don't have permission to "add" on "ssh_key"

To Reproduce
Steps to reproduce the behavior:

1. run lagoon add user-sshkey -E [email protected] -K path/to/file -p project-x -N ssh-rsa
2. See error

Expected behavior
The ssh key gets added.

Sort the options by alpha for all commands

Is your feature request related to a problem? Please describe.

At the moment the options are all over the place, and you need to scan them all to find the one you want. e.g.:

$ lagoon delete -h
Delete a project, or delete notifications and variables from projects or environments

Usage:
  lagoon delete [command]

Aliases:
  delete, d

Available Commands:
  variable           Delete a variable from an environment
  user-group         Delete a user from a group in lagoon
  project-group      Delete a project from a group in lagoon
  user               Delete a user from lagoon
  group              Delete a group from lagoon
  project-slack      Delete a slack notification from a project
  slack              Delete a slack notification from lagoon
  project-rocketchat Delete a rocketchat notification from a project
  rocketchat         Delete a rocketchat notification from lagoon
  user-sshkey        Delete an sshkey from lagoon
  environment        Delete an environment
  project            Delete a project

Describe the solution you'd like

Sort Available Commands: by alphabetical order ASC.

Unable to change project name

Describe the bug
Using the CLI, I am unable to change a projects name using the update project command

db/files sync between environments

Is your feature request related to a problem? Please describe.
As a developer on a project, I need a simple method to synchronize a database and/or persistent files between environments of my project, as well as to my local environment. Currently this is only a simple thing for Drupal projects, utilizing drush sql-sync and drush rsync to do this.

Describe the solution you'd like
Something like lagoon sync db`lagoon sync files` to handle setting up the connection and syncing the requested resource.

lagoon web command bug

Describe the bug

1. The docs do not say how to use this command correctly, it says lagoon web [flags] but it actually requires the project name as the first requirement. By tinkering I figured out it was (for project ipsum) lagoon web ipsum.

• Please add a Usage: section to each command doc page that shows simple examples.
• Change the Synopsis to lagoon web [project name] [flags]

2. When the browser is opened after running the command, the url is malformed and results in a 500 response. The correct url pattern is https://ui-lagoon-master.ch.amazee.io/projects/ipsum but the lagoon command opens is as https://ui-lagoon-master.ch.amazee.io/projects?name=ipsum

Integration with oh-my-zsh plugins

Is your feature request related to a problem? Please describe.

I would love to know which lagoon I am currently logged into in my PS1. Basically this value:

cat ~/.lagoon.yml | shyaml get-value current

I wonder if a oh-my-zsh plugin could be published.

Command to launch the web UI

Incorporate pymgy-go inside lagoon cli

Panic if SSH key not found

Describe the bug
lagoon login tries to open /home/scott/.ssh/id_rsa and panics if that file is not found.

To Reproduce
Steps to reproduce the behavior:

1. If you have a file in ~/.ssh/id_rsa, move it elsewhere temporarily.
2. run lagoon login

Expected behavior
SSH supports multiple key formats. According to man ssh:

The default is ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519 and ~/.ssh/id_rsa.

I'm using ed25519.

So I guess it should try to load the keys in the same order the SSH client does..?

Screenshots

$ lagoon version
Version: 0.6.1
Build: 2019-12-06T04:46:13+0000
$ lagoon login
panic: open /home/scott/.ssh/id_rsa: no such file or directory

goroutine 1 [running]:
github.com/amazeeio/lagoon-cli/cmd.publicKey(0xc0000b1480, 0x17, 0xc00012db00, 0x1, 0x1, 0xc0000b1480)
	/go/src/github.com/amazeeio/lagoon-cli/cmd/login.go:31 +0x751
github.com/amazeeio/lagoon-cli/cmd.loginToken(0x0, 0x0)
	/go/src/github.com/amazeeio/lagoon-cli/cmd/login.go:76 +0xdc
github.com/amazeeio/lagoon-cli/cmd.validateToken(0xc0000af2e8, 0x8)
	/go/src/github.com/amazeeio/lagoon-cli/cmd/root.go:272 +0x4f
github.com/amazeeio/lagoon-cli/cmd.glob..func28(0xe59340, 0xe86508, 0x0, 0x0)
	/go/src/github.com/amazeeio/lagoon-cli/cmd/login.go:21 +0x5f
github.com/spf13/cobra.(*Command).execute(0xe59340, 0xe86508, 0x0, 0x0, 0xe59340, 0xe86508)
	/go/pkg/mod/github.com/spf13/[email protected]/command.go:830 +0x2ae
github.com/spf13/cobra.(*Command).ExecuteC(0xe5bb40, 0x0, 0x0, 0x8cc213)
	/go/pkg/mod/github.com/spf13/[email protected]/command.go:914 +0x2fc
github.com/spf13/cobra.(*Command).Execute(...)
	/go/pkg/mod/github.com/spf13/[email protected]/command.go:864
github.com/amazeeio/lagoon-cli/cmd.Execute()
	/go/src/github.com/amazeeio/lagoon-cli/cmd/root.go:58 +0x42
main.main()
	/go/src/github.com/amazeeio/lagoon-cli/main.go:8 +0x20

Desktop (please complete the following information):

• OS: Debian Testing (Linux)

Additional context
I'm using the linux-amd64 binary downloaded from the github releases page.

Run a task

See the following mutations

• taskDrushArchiveDump(environment: Int!): Task
• taskDrushSqlDump(environment: Int!): Task
• taskDrushCacheClear(environment: Int!): Task

Use the current .lagoon.yml for project context

This CLI should assume you are working against a project and check for a .lagoon.yml. If not, prompt for what project to check.

`lagoon web <project>` command provides incorrect URL

Describe the bug
When attempting to open the UI page of a project, the URL the Lagoon CLI provides is incorrect.

To Reproduce

1. Run lagoon web <project>
2. Browser will open to https://ui-lagoon-master.ch.amazee.io/project?name=

Expected behavior
Browser should open https://ui-lagoon-master.ch.amazee.io/projects/

Improve flags for commands

A lot of the current commands rely on arguments being passed to them. It makes sense to use flags instead.

Create docs on local development

Would be nice to know for people new to Lagoon CLI development, how to get started, where important bits of code live, common pitfalls etc.

Token error on re-auth

Describe the bug

If I have to re-auth to the API to get a new token, sometimes I get an error like this.

$ lagoon list projects --all-projects
Error: graphql: Forbidden - Invalid Auth Token: Error decoding token: invalid algorithm

I know it's re-authing because I get a pinentry popup for my SSH agent.

If I run the lagoon command again immediately it will work - and continue working.

To Reproduce
Steps to reproduce the behavior:

1. Wait for your token to expire (or invalidate it by editing ~/.lagoon.yml).
2. Run a lagoon CLI command.
3. See error.
4. Run another command, works fine this time.

Expected behavior
Token should be renewed without error.

Screenshots
n/a

Desktop:

• OS: Debian testing

Additional context
Debug output (not sure if it's helpful).
Failure:

$ lagoon list projects --all-projects --debug
Request: {"query":"\nquery {\nallProjects {\n...Project\n}\n}fragment Project on Project {\nid\ngitUrl\nname,\ndevelopmentEnvironmentsLimit,\nenvironments {\nenvironmentType,\nroute\n}\n}","variables":null}
Error: graphql: Forbidden - Invalid Auth Token: Error decoding token: invalid token

Success:

$ lagoon list projects --all-projects --debug
Request: {"query":"\nquery {\nallProjects {\n...Project\n}\n}fragment Project on Project {\nid\ngitUrl\nname,\ndevelopmentEnvironmentsLimit,\nenvironments {\nenvironmentType,\nroute\n}\n}","variables":null}
Response: ... snipped

allow adding of Teams and email notifications

Lagoon now supports notifications to Microsoft Teams and email, these should be present as options in lagoon-cli.