CLI Documentation

Documentation for the Porter CLI.

Installation

Mac

Run the following command to grab the latest binary:

{
name=$(curl -s https://api.github.com/repos/porter-dev/porter/releases/latest | grep "browser_download_url.*/porter_.*_Darwin_x86_64\.zip" | cut -d ":" -f 2,3 | tr -d \")
name=$(basename $name)
curl -L https://github.com/porter-dev/porter/releases/latest/download/$name --output $name
unzip -a $name
rm $name
}

Then move the file into your bin:

chmod +x ./porter
sudo mv ./porter /usr/local/bin/porter

To download a specific version of the CLI:

{
# NOTE: replace this line with the version
version=v0.6.1
name=porter-$version.zip
curl -L https://github.com/porter-dev/porter/releases/download/${version}/porter_${version}_Darwin_x86_64.zip --output $name
unzip -a $name
rm $name
chmod +x ./porter
sudo mv ./porter /usr/local/bin/porter
}

Linux

Run the following command to grab the latest binary:

{
name=$(curl -s https://api.github.com/repos/porter-dev/porter/releases/latest | grep "browser_download_url.*/porter_.*_Linux_x86_64\.zip" | cut -d ":" -f 2,3 | tr -d \")
name=$(basename $name)
curl -L https://github.com/porter-dev/porter/releases/latest/download/$name --output $name
unzip -a $name
rm $name
}

Then move the file into your bin:

chmod +x ./porter
sudo mv ./porter /usr/local/bin/porter

To download a specific version of the CLI:

{
# NOTE: replace this line with the version
version=v0.6.1
name=porter-$version.zip
curl -L https://github.com/porter-dev/porter/releases/download/${version}/porter_${version}_Linux_x86_64.zip --output $name
unzip -a $name
rm $name
chmod +x ./porter
sudo mv ./porter /usr/local/bin/porter
}

Windows

Go here to download the Windows executable and add the binary to your PATH.

Connecting to an existing cluster

porter connect kubeconfig

Connects Porter to an existing Kubernetes cluster using the current-context in your kubeconfig.

Pushing Docker images to your Porter image registry

🚧

You must be logged in before configuring registry access

Please make sure you are logged in by running porter config set-host https://dashboard.getporter.dev; porter auth login first.

porter docker configure

Writes to the local Docker config.json file to grant push/pull access to the image registries provisioned by Porter. Once you have run this command, you can directly use the docker CLI to push to the private image registry.

Example:

porter docker configure
docker build . -t gcr.io/project-123456/porter-server:latest
docker push gcr.io/project-123456/porter-server:latest

πŸ“˜

We are working to add support for additional private Docker registries. If you don't see your registry provider, send us an email at [email protected] or feel free to contribute to the repo.

Connecting the CLI to a locally running instance of Porter

porter config set-host [HOST]

Sets the URL of the Porter API server the CLI will communicate with. HOST is a URL including the protocol and defaults to https://dashboard.getporter.dev.

For locally running porter instances, run:

porter config set-host http://localhost:8080

Remote Execution

porter run [RELEASE] -- [COMMAND] [args...]

🚧

Prequisites

Note: before running this command, you should make sure your cluster is set in your config. Run porter clusters list to view the list of connected clusters, and run porter config set-cluster [ID] to set the correct cluster in your config.

Allows users to execute a command on a remote container. The release variable is the name of the release on the Porter dashboard (this can be a release either in the "Applications" or the "Jobs" tab). For example, if I have a release called web, and I would like to enter an interactive shell in the container attached to web, I would run:

porter run web -- sh

To test that remote execution is working, you can run:

porter run web -- echo "hello world"

To run in a namespace other than default, use the --namespace flag:

porter run web --namespace other-namespace -- sh

Commands

Here's a reference table for the CLI documentation:

CommandDescription
porter config set-host [HOST]Sets the API server host name that the CLI will communicate with.
porter auth loginLogs in via the CLI.
porter config set-project [PROJECT_ID]Sets the current project in config.
porter connect [INTEGRATION]Connects Porter with the given infrastructure. Accepts kubeconfig and ecr as arguments.
porter docker configureGrants the docker CLI access to a provisioned image registry.
porter run [RELEASE] -- [COMMAND] [args...]Executes a command on a remote container, specified by the release name.