Rename project and binary

[dylanratcliffe]

Background

We want the new CLI to be as easy to use as possible. To this end we want user to basically be able to run overmind terraform plan in place of where they would previously run terraform plan. In order to do this though we need to reorganise the CLI

Tasks

• Rename this project from ovm-cli to cli
• Rename the binary that is produced to overmind (pretty sure this will happen automatically)
• See if we can separate the existing commands in the help text. We want the "happy path" of using the overmind terraform command to be super obvious. We might be able to separate this somehow, or maybe we will need to nest them under a subcommand. (Cobra claims "Grouping help for subcommands" as a feature)
• Update the Github Actions to use the new binary and different commands if we changed them (Done in the rename-cli branch)
• Merge the rename-cli branch in the Github action
• Find all the places this repo is used in the website and replace (though github will give us a redirect for some time)
• Now that we are using a hierarchy, review all of the arguments and move them to where they are actually required. Ideally the terraform command wouldn't accept any arguments that are Overmind-specific for example
• Update the Readme with an interim description

Subcommand vs Group

Is is possible to group commands which gives you output like this:

$ overmind help
Calculate the blast radius of your changes, track risks, and make changes with confidence

Usage:
  overmind [command]

Infrastructure as Code Commands

Utility Commands
  create-bookmark        Creates a bookmark from JSON.
  end-change             Finishes the specified change. Call this just after you finished the change. This will store a snapshot of the current system state for later reference.
  get-affected-bookmarks Calculates the bookmarks that would be overlapping with a snapshot.
  get-bookmark           Displays the contents of a bookmark.
  get-change             Displays the contents of a change.
  get-snapshot           Displays the contents of a snapshot.
  list-changes           Displays the contents of a change.
  list-invites           List all invites
  manual-change          Creates a new Change from a given query
  request                Runs a request against the overmind API
  start-change           Starts the specified change. Call this just before you're about to start the change. This will store a snapshot of the current system state for later reference.
  submit-plan            Creates a new Change from a given terraform plan file

Additional Commands:
  completion             Generate the autocompletion script for the specified shell
  create-invite          Create a new invite
  help                   Help about any command
  revoke-invites         Revoke an existing invite

Flags:
      --api-key string             The API key to use for authentication, also read from OVM_API_KEY environment variable
      --api-key-url string         The overmind API Keys endpoint (defaults to --url)
      --auth0-client-id string     OAuth Client ID to use when connecting with auth (default "j3LylZtIosVPZtouKI8WuVHmE6Lluva1")
      --auth0-domain string        Auth0 domain to connect to (default "om-prod.eu.auth0.com")
      --gateway-url string         The overmind Gateway endpoint (defaults to /api/gateway on --url)
  -h, --help                       help for overmind
      --honeycomb-api-key string   If specified, configures opentelemetry libraries to submit traces to honeycomb. This requires --otel to be set.
      --json-log                   Set to true to emit logs as json for easier parsing.
      --log string                 Set the log level. Valid values: panic, fatal, error, warn, info, debug, trace (default "info")
      --otel                       If specified, configures opentelemetry and - optionally, see --sentry-dsn - sentry using their default environment configs.
      --run-mode string            Set the run mode for this service, 'release', 'debug' or 'test'. Defaults to 'release'. (default "release")
      --sentry-dsn string          If specified, configures sentry libraries to capture errors. This requires --otel to be set.
      --stdout-trace-dump          Dump all otel traces to stdout for debugging. This requires --otel to be set.
      --url string                 The overmind API endpoint (default "https://api.prod.overmind.tech")
  -v, --version                    version for overmind

Use "overmind [command] --help" for more information about a command.

The problem is that I think this is way too much text for a default help command. There are a number of things here that users will likely never use like creating invites, I am thinking maybe we should group these based on the service in the API so that they are more similar using both groups and subcommands. This would mean it would look like this:

$ overmind help
Calculate the blast radius of your changes, track risks, and make changes with confidence

Usage:
  overmind [command]

Infrastructure as Code Commands
  terrafrorm             Run Terraform with Overmind as a wrapper calculating the blast radius and risks

Overmind API
  changes                Create, update and delete changes in Overmind
  bookmarks              Interact with the bookarks that were created in the Explore view
  snapshots              Create, view and delete snapshots if your infrastructure
  invites                Manage invitations to your Overmind team

Additional Commands:
  completion             Generate the autocompletion script for the specified shell
  help                   Help about any command

Flags:
      --api-key string             The API key to use for authentication, also read from OVM_API_KEY environment variable
      --api-key-url string         The overmind API Keys endpoint (defaults to --url)
      --auth0-client-id string     OAuth Client ID to use when connecting with auth (default "j3LylZtIosVPZtouKI8WuVHmE6Lluva1")
      --auth0-domain string        Auth0 domain to connect to (default "om-prod.eu.auth0.com")
      --gateway-url string         The overmind Gateway endpoint (defaults to /api/gateway on --url)
  -h, --help                       help for overmind
      --honeycomb-api-key string   If specified, configures opentelemetry libraries to submit traces to honeycomb. This requires --otel to be set.
      --json-log                   Set to true to emit logs as json for easier parsing.
      --log string                 Set the log level. Valid values: panic, fatal, error, warn, info, debug, trace (default "info")
      --otel                       If specified, configures opentelemetry and - optionally, see --sentry-dsn - sentry using their default environment configs.
      --run-mode string            Set the run mode for this service, 'release', 'debug' or 'test'. Defaults to 'release'. (default "release")
      --sentry-dsn string          If specified, configures sentry libraries to capture errors. This requires --otel to be set.
      --stdout-trace-dump          Dump all otel traces to stdout for debugging. This requires --otel to be set.
      --url string                 The overmind API endpoint (default "https://api.prod.overmind.tech")
  -v, --version                    version for overmind

Use "overmind [command] --help" for more information about a command.

I think this would be a bit better for a few reasons:

• It would be obvious where new functionality should go for actions that are direct API interactions since they can simply sit in the same subcommands share names with the API actions that they call. This would help developers building this CLI as there are less decisions to make
• Users that are familiar with the API could easily find where in the CLI they need to poke to get the API to do something and vice-versa

Arguments

I want to get rid of all the arguments on the root command, to that end I have audited the ones that we have and what they are used for:

• --url Move this to all of the API endpoints, consider what to do about Terraform though....
  • All auth clients use this
  • Lots of things use this for logging
  • Used in ensureToken() which is used in basically everything
  • A couple of things use the directly for determing the URL of the API endpoint:
    • changes manual-change
    • changes submit-plan
    • request
    • TODO: Why only these three? Wouldn't all endpoints need to construct a similar URL
• --gateway-url REMOVE, only use base URL
  • As an override for url in"
    • changes manual-change
    • changes submit-plan
    • request
• --api-key
  • Used in ensureToken() which is everywhere
• --api-key-url REMOVE, only use base URL
  • Most of the auth clients
  • Logs
• --auth0-client-id Can probably remove this
  • ensureToken()
• --auth0-domain Can probably remove this
  • ensureToken()
• --otel REMOVE
  • Nowhere
• --honeycomb-api-key Move to env var, only configure tracing if set. Could also set this to hidden so that it doesn't show up in the help output
  • Root cmd pre-run
• --sentry-dsn REMOVE
  • Nowhere
• --run-mode REMOVE
  • Nowhere
• --json-log REMOVE
  • Root cmd pre-run
• --stdout-trace-dump REMOVE
  • Nowhere

[DavidS-ovm]

Please also open a ticket for moving the actions over to the new naming scheme and #173