CLI basic usage

This guide covers the essential commands and configuration options for the Porter CLI.

Quick Start

Authenticate with your Porter account:

porter auth login

This opens your browser to complete authentication and automatically configures your default project and cluster.

Verify Configuration

Check your current CLI configuration:

porter config

If necessary, switch your project and/or cluster

Deploy Your App

Deploy using a porter.yaml file:

porter apply -f porter.yaml

porter.yaml referenceporter apply reference

Project and Cluster Configuration

After logging in, you may need to switch between projects or clusters.

List Available Projects

porter projects list

Set Active Project

porter config set-project [PROJECT_ID]

List Available Clusters

porter clusters list

The default table does not include cluster IDs. Pass --json when you need the ID for the next command:

porter clusters list --json

Set Active Cluster

porter config set-cluster [CLUSTER_ID]

View Current Configuration

porter config

Global Flags

These flags can be used with any Porter command:

Flag	Description
`--project <id>`	Override the project ID for this command
`--cluster <id>`	Override the cluster ID for this command
`--token <string>`	Use a specific authentication token
`-h, --help`	Display help for the command

porter app logs my-app --project 12345

porter app run my-app --cluster 67890 -- bash

Environment Variables

Environment variables provide an alternative way to configure the CLI, which is especially useful in CI/CD pipelines.

Variable	Description	Equivalent Flag
`PORTER_PROJECT`	Project ID to use	`--project`
`PORTER_CLUSTER`	Cluster ID to use	`--cluster`
`PORTER_TOKEN`	Authentication token	`--token`
`PORTER_HOST`	Custom Porter API host	`--host`
`PORTER_APP_NAME`	Default app name for commands	`--app`

Environment variables take precedence over values in your config file, but flags take precedence over environment variables.

Example: CI/CD Configuration

export PORTER_TOKEN="your-deploy-token"
export PORTER_PROJECT="12345"
export PORTER_CLUSTER="67890"

porter apply -f porter.yaml

Common Workflows

Local Development

# Login and configure
porter auth login

# View your app's logs
porter app logs my-app

# Run a command in an ephemeral copy of your app
porter app run my-app -- bash

# View current app configuration
porter app yaml my-app

CI/CD Deployment

# Deploy with explicit configuration
PORTER_TOKEN=$DEPLOY_TOKEN \
PORTER_PROJECT=$PROJECT_ID \
PORTER_CLUSTER=$CLUSTER_ID \
porter apply -f porter.yaml

Managing Environment Variables

# Pull environment variables from an app
porter env pull -a my-app

# Pull environment variables from an environment group
porter env pull -g my-env-group

# Set environment variables on an app
porter env set -a my-app -v KEY=value

# Set secrets on an environment group
porter env set -g my-env-group -s API_KEY=secret123

Debugging

# Stream live logs
porter app logs my-app

# View historical logs
porter app logs my-app --since 1h

Viewing Help

You can view help instructions for any command using the -h or --help flag:

# General help
porter -h

# Help for a specific command
porter app -h

# Help for a subcommand
porter app run -h

Next Steps

Learn about configuration-as-code with porter.yaml
Explore the full command reference for detailed options
Set up CI/CD deployment for automated deployments

​Quick Start

​Project and Cluster Configuration

​List Available Projects

​Set Active Project

​List Available Clusters

​Set Active Cluster

​View Current Configuration

​Global Flags

​Environment Variables

​Example: CI/CD Configuration

​Common Workflows

​Local Development

​CI/CD Deployment

​Managing Environment Variables

​Debugging

​Viewing Help

​Next Steps

Quick Start

Project and Cluster Configuration

List Available Projects

Set Active Project

List Available Clusters

Set Active Cluster

View Current Configuration

Global Flags

Environment Variables

Example: CI/CD Configuration

Common Workflows

Local Development

CI/CD Deployment

Managing Environment Variables

Debugging

Viewing Help

Next Steps