Install and configure

Choose an installation method, then authenticate so you can call the Port API from the shell or CI.

Install

Install the Port CLI in one of the following ways:

npm

npm install -g @port-labs/port-cli
port --version

Quick install script

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/port-labs/port-cli/main/scripts/install.sh | bash

This downloads and installs the latest release binary to /usr/local/bin (or ~/.local/bin if you do not have write permissions).

Binary releases

Download pre-built binaries for your platform from GitHub Releases.

Docker

Build the image from the repository:

docker build -t port-cli .

Run a command:

docker run --rm \
  -e PORT_CLIENT_ID="your-client-id" \
  -e PORT_CLIENT_SECRET="your-client-secret" \
  port-cli --help

Export with output written to the host:

docker run --rm \
  -e PORT_CLIENT_ID="your-client-id" \
  -e PORT_CLIENT_SECRET="your-client-secret" \
  -v $(pwd)/output:/data \
  port-cli export --output /data/backup.tar.gz

Build from source

For development or the latest unreleased code:

git clone https://github.com/port-labs/port-cli.git
cd port-cli
make build
./bin/port --help

When you build from source, use ./bin/port instead of port in commands. See INSTALL.md in the repository for more detail.

After installing, verify with port --version.

Experimental CLI

If you previously installed the experimental CLI (@port-experimental/port-cli), uninstall it first:

npm uninstall -g @port-experimental/port-cli

Authenticate

You can authenticate with a short-lived user token (browser login) or with machine credentials (client_id and client_secret). Machine credentials do not expire, so they are less secure than a user token. Prefer browser login for interactive use, and machine credentials for CI and scripts.

Most commands work with either method. Browser login stores an OAuth token in ~/.port/creds.json.

Browser login

port auth login

This opens a browser, generates a short-lived token, and lets you act on behalf of your user. Use port auth login --region when you need to pick EU or US.

Machine credentials

Use the Client ID and Client Secret from your Port application settings (see credentials and secrets), not the organization ID.

If your organization is in the US region, set PORT_API_URL (or api_url) to https://api.us.getport.io/v1. The EU default is https://api.getport.io/v1.

Supply credentials in one of the following ways:

Environment variables

Good for CI and one-off shells:

export PORT_CLIENT_ID="your-client-id"
export PORT_CLIENT_SECRET="your-client-secret"
export PORT_API_URL="https://api.getport.io/v1"

port export --output backup.tar.gz

~/.port/.env

Persistent on your machine, same variable names:

# ~/.port/.env
PORT_CLIENT_ID=your-client-id
PORT_CLIENT_SECRET=your-client-secret
PORT_API_URL=https://api.getport.io/v1

Config file

Run port config --init, then edit ~/.port/config.yaml:

default_org: production

organizations:
  production:
    client_id: your-client-id
    client_secret: your-client-secret
    api_url: https://api.getport.io/v1

Per-command flags

Highest precedence:

port api blueprints list \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --api-url https://api.getport.io/v1

Many subcommands accept flags instead of prompts. Use port --yes / -y to skip confirmation prompts where supported.

After you authenticate, try a simple read or export to confirm the CLI can reach your organization, for example:

port api call /blueprints
port api blueprints list
port export --output backup.tar.gz

Configuration reference

When the same setting is provided in more than one place, the CLI uses this order (highest wins): CLI args > env vars > config file > defaults.

For example, --api-url on the command overrides PORT_API_URL, which overrides api_url in ~/.port/config.yaml.

The CLI also loads ~/.port/.env (and a .env file in the current directory) at startup. Existing shell environment variables are not overridden.

Configuration file

You can define multiple organizations in ~/.port/config.yaml:

default_org: production

organizations:
  production:
    client_id: production-client-id
    client_secret: production-client-secret
    api_url: https://api.getport.io/v1

  staging:
    client_id: staging-client-id
    client_secret: staging-client-secret
    api_url: https://api.getport.io/v1

Environment variables

Variable	Purpose
PORT_CLIENT_ID	Port API client ID.
PORT_CLIENT_SECRET	Port API client secret.
PORT_API_URL	Port API URL (optional; default https://api.getport.io/v1).
PORT_CONFIG_FILE	Path to the config file.
PORT_DEFAULT_ORG	Default organization name.
PORT_DEBUG	Enable debug mode.

Coding agents

Copy your client ID and client secret into an environment the agent can read (working-directory .env or ~/.port/.env), then ask the agent to install @port-labs/port-cli and run port. For cloud agents, add the same values as workspace or run secrets.

Next steps

• Usage and examples.
• Manage Port across environments.