Port CLI
The Port CLI does not use Port AI capabilities. You can install and use it without enabling Port AI features or accepting the Port AI Terms.
Port CLI (port) is a command-line client for the Port API. Coding agents run it from the shell, print raw JSON, pipe it through jq or a script, and batch updates without pulling every result into context. Platform engineers use the same binary to export, import, compare, and migrate organizations.
The Port MCP server answers named catalog questions through a fixed set of tools. It does not run your code or print raw JSON. Use MCP for chat. Use this CLI when the agent needs stdout it can filter.
Who it is for
- People running Cursor, Claude Code, Codex, or similar against Port.
- Platform engineers who maintain more than one Port org (staging and production, sandbox rebuilds, CI gates).
Example use cases
Query the catalog
Run port api call /blueprints, then pipe the JSON through jq.
port api call /blueprints | jq
Batch updates and workflows
Write a script that calls port api to update entities or trigger actions. Only the script result hits the model context.
port api entities update service payments --data ./payments.json
Compare, export, or migrate organizations
Print a diff between two orgs, then fail CI when they drift.
port compare --source staging --target production --fail-on-diff
How to use it
- Coding agents (local)
- Cloud agents
- Local login
Copy your client ID and client secret from credentials and secrets. Put them in an environment the agent can read:
PORT_CLIENT_ID=your-client-id
PORT_CLIENT_SECRET=your-client-secret
Save that file as .env in the working directory or as ~/.port/.env.
Ask the agent to install the CLI and list blueprints:
npm install -g @port-labs/port-cli
port api blueprints list
If your organization is in the US region, set PORT_API_URL to https://api.us.getport.io/v1. The EU default is https://api.getport.io/v1.
This path works for Cursor, Claude Code, Codex, and similar agents running on your machine. The agent uses Bash the way it uses gh.
Add PORT_CLIENT_ID and PORT_CLIENT_SECRET as environment secrets for the workspace or cloud run. Copy the values from credentials and secrets.
Tell the agent to install @port-labs/port-cli and call port:
npm install -g @port-labs/port-cli
port api blueprints list
If your organization is in the US region, also set PORT_API_URL to https://api.us.getport.io/v1.
Cursor Agent and Cursor Cloud follow this path. Add the two secrets, then ask the agent to install the package and run port. The agent uses Bash the way it uses gh.
Install the CLI, then log in with your Port user. The browser flow stores a short-lived user token.
npm install -g @port-labs/port-cli
port auth login
You can also authenticate with a client ID and client secret. Those credentials do not expire, so they are less secure than a user token. See credentials and secrets.
Learn more
The port-labs/port-cli repository includes the source, the README with the command list, configuration, and examples (backup, compare, clear, migrate, Docker), and known issues. Open a GitHub issue when something does not match.
Install the npm package @port-labs/port-cli. If @port-experimental/port-cli is installed, uninstall it first: npm uninstall -g @port-experimental/port-cli.
Related docs: