CommandK CLI

The CommandK CLI is a command line interface for interacting with the CommandK API. The CLI is currently available for Linux, and macOS.

CommandK CLI
- Download and Install
  - Homebrew (MacOS)
  - Linux (or MacOS without brew)
- Setup
Operations
Working with frameworks
- Next.js
- NestJS
- Nuxt
- Gatsby
- Remix
- Vite
- Django
- Flask
- Laravel
- .NET
- Spring boot
Configuring the CLI
Auditing CLI Access

Download and Install

Homebrew (MacOS)

To install the commandk cli via homebrew, use the CommandK homebrew tap

$ brew tap commandk-dev/packages
$ brew install cmdk-cli

If the installation went through smoothly, you should be able to run:

$ cmdk version

Linux (or MacOS without brew)

The CommandK CLI can be downloaded from the releases page, or get the latest using:

# For Linux
curl -L https://github.com/commandk-dev/cli/releases/download/v0.1.4/cmdk-cli-client-0.1.4-linux-x86_64.zip \
    --output cmdk-cli-client-0.1.4-linux-x86_64.zip

# For MacOS
curl -L https://github.com/commandk-dev/cli/releases/download/v0.1.4/cmdk-cli-client-0.1.4-osx-x86_64.zip \
    --output cmdk-cli-client-0.1.4-osx-x86_64.zip

After downloading the ZIP file, extract its contents using the following command (replace with the actual downloaded file name), and install the binary:
```
$ unzip /path/to/archive.zip
$ # You might have to use sudo for the next command
$ install <archive>/cmdk-linux-x86_64 -m 0555 /usr/local/bin/cmdk
```

If the installation went through successfully, you should be able to run:

$ cmdk version

Setup

To begin using the CLI, you'll first need to get an access token. To do that, head over to the CommandK dashboard, and on the left panel, click on Settings > API Access. In the tab that opens up, in the top-right corner, click on the button that says "New token". Enter a memorable name for your API token, select the applications that you want this token to be able to access to, and the environments that you want to restrict this action to. You can also select the scope of the token to be either Read or Write. Do note that, Write is not a superset of a Read token, and a Write token does not allow any Read operations.

Click on "Create" and copy the access token that was generated. Do note that we do not display the access token once this panel is collapsed, so make sure you copy the token before dismissing the panel.

Create a new file named .commandk.config.json in your home directory with the following data:

{
    "api-access-token": "... the token you just created ..."
}

NOTE You MUST be an Admin or an Owner to be able to create API Access tokens

NOTE If you wish to use application names while using the CLI, then you must select the "all" apps option. If you are using tokens that are restricted to certain apps, then you must use app identifiers when using the CLI Check the section on Application names and identifiers for details on how to do this.

Now you are all setup to start using the CommandK CLI!

NOTE If you are using an on-prem installation of the CLI, you'll have to specify an alternate endpoint in your .commandk.config.json file. Your file would look like:
{
   "api-access-token": "<your-access-token>",
   "api-endpoint": "https://api.<installation-name>.commandk.dev"
}
For the value of api-endpoint, refer to the Customer Information Sheet that would have been shared by the CommandK team for your installation. Usually, if you access your dashboard at app.<name>.commandk.dev, then the API endpoint would be https://api.<name>.commandk.dev

Operations

Getting Secrets

To get secrets for an application, you can use the cmdk secrets get command. It follows the format:

$ cmdk secrets get <application-name> --environment <environment-name> --output-file-name <file-name>

For example,

$ cmdk secrets get return-management-service \
     --environment staging \
     --output-file-name my-secrets.env
Writing fetched secrets to file `my-secrets.env`

By default, secrets are always written in the "env" format, where each key/value pair is listed on a line, with they key and value being seperated by a = sign. The CLI also supports output in json and yaml format, which you can specify using the --output flag. For example,

$ cmdk secrets get return-management-service \
     --environment staging \
     --output-file-name my-secrets.json \
     --output json

Owing to the sensitive nature of secrets, the CLI does not support writing secrets to stdout. If you wish to pipe values to a script, you can use a temp file in your script.

Running Commands with Secrets

In addition to writing secrets to a file, you can also run a command with the secrets being injected to environment variables for the command, or alternatively, to write to a file and then execute a command - the latter being a convenience mechanism that gives you a single command to fetch secrets and run your applications.

Running with environment variables

To execute a process with fetched secrets as environment variables, you can use the command cmdk run:

$ cmdk run <application-name> --environment <environment-name> -- <command>

For example,

$ cmdk run return-management-service --environment development -- node index.js

This command will populate the secrets for return-management-service within the environment development and present them as environment variables to the command.

Running with storing to a file

To fetch secrets to a file and then execute a command, you can use the --run-type file-store flag. For example,

$ cmdk run return-management-service \
      --environment development \
      --run-type file-store \
      --file-name env.json \
      --file-format json \
      -- node index.js

The arguments --file-name and --file-format specify the name of the file and the format the secrets are written in before executing the specified command.

Importing Secrets

To import secrets, get the app name from the dashboard you want to import secrets for. Then create a file, with any name, for ex. secrets-staging.json with the following structure:

{
  "database_password": "<your-db-passworD>",
  "api_key": "<your-api-key>",
  "encryption_key": "<your-encryption-key>"
}

To use this file to import secrets to an app, use the cmdk secrets import command:

$ cmdk secrets import return-service-management \
     --environment staging \
     --import-file secrets-staging.json
✅ Using environment Development [id: yueOX-iOZN-UapbH-ruAP]
Read [3] secrets to upload
Using application with UUID [6L4Wd-oY7z-eLCFv-qc8R]
Wrote secret [database_password]
Wrote secret [api_key]
Wrote secret [encryption_key]

NOTE You will need to use an API access token with Write scope to be able to run this command.

Getting help with options and arguments

All subcommands are documented and can be listed by passing in the --help flag. To get a list of the base commands, simply run

$ cmdk --help
Usage: cmdk [<options>] <command> [<args>]...

  cmdk

Options:
  --api-access-token=<text>  The API Access Token used to make API calls
  --api-endpoint=<text>      The HTTPs endpoint for the CommandK API Server
  -h, --help                 Show this message and exit

Commands:
  secrets  Perform operations on secrets via the CommandK CLI
  run      Fetch secrets, and invoke the application runner

To get more information about a specific subcommand, simply run that command with the --help flag, for example, to get more information about the secrets import command, or the run command execute:

$ cmdk secrets import --help

$ cmdk run --help

Application names and identifiers

All CLI actions invariably operate on a particular app within CommandK. For ease of use, by default the CLI always accepts application names, but in environments where you would like to use something more predictable and robust, you can specify app identifiers as well. Whenever using an application identifier instead of an app name, simply specify the flag --identifier-type Identifier (this flag defaults to Name). For example:

$ cmdk secrets get LDJML-6x65-saP5d-7jBL \
     --identifier-type Identifier \
     --environment staging \
     --output-file-name secrets.env

The app id can be fetched from the side panel under the "Settings" tab, for a given app:

Working with frameworks