Overview

The Ampersand Command Line Interface (CLI) enables you to deploy integrations and interact with the Ampersand platform.

​

Installation

​

For macOS using Homebrew

To install the CLI using Homebrew (macOS users):

brew tap amp-labs/cli
brew update
brew install amp-labs/cli/cli

​

Updating to new version

If you already have the CLI installed, and want to upgrade to the latest version, run:

brew upgrade amp-labs/cli/cli

​

For Windows

1. Visit Ampersand CLI Releases.

2. Download the appropriate binary for your machine’s architecture.

3. Extract the downloaded folder containing the exe file.

4. To use the CLI, open Command Prompt in the extracted folder:

   • Navigate to the folder in File Explorer
   • Click in the address bar
   • Type cmd and press Enter

5. Verify the installation by running:

   amp
   

   This should display a list of commands or options available in the CLI, confirming that it is properly configured and ready for use.

6. To make the CLI accessible from anywhere, add the folder to your PATH:

   • Open the Start menu
   • Search for “Environment Variables”
   • Click “Edit the system environment variables”
   • Click “Environment Variables”
   • Under “System variables”, select “Path” and click “Edit”
   • Click “New” and add the path to the folder containing the exe file
   • Click “OK” on all windows

​

For other systems

1. Visit Ampersand CLI Releases.
2. Download the appropriate binary for your machine’s architecture.
3. Place the binary somewhere on your PATH (e.g. /usr/bin).

Note:
To ensure the CLI is accessible from anywhere, the binary must be placed in a directory listed in your PATH. You can inspect your current PATH using the following commands:

• Linux/macOS:

  echo $PATH
  

​

Using the CLI

​

Checking the version

To check the version and build information of your CLI, run:

amp version

​

Log into your Ampersand account

Ensure you have an Ampersand account. Create one on the Ampersand Dashboard if you don’t already have one.

To log into the CLI:

amp login

To log out:

amp logout

​

Deploy integrations

Once you have defined your integrations in an amp.yaml file, use the following commands to deploy:

amp login
amp deploy <folder_with_amp.yaml> --project <id-or-name>

​

View all commands

To list all available commands and global flags:

amp help

Note: For detailed explanations of each command and its options, refer to the Command Reference section.

​

Running in CI/CD Environments

If you are using the Ampersand CLI in a CI/CD system (e.g. GitHub Actions):

1. Generate an API key in the Ampersand Dashboard.
2. Use the API key with the key flag.

amp list:integrations --key <api-key> --project <id-or-name>

Alternatively, you can set the API key as an environment variable:

export AMP_API_KEY=<api-key>
amp list:integrations --project <id-or-name>

​

Debug mode

For more detailed output, run commands with the debug flag.

amp login --debug