Usage and examples

This page lists the main CLI commands and common workflows. It assumes the CLI is installed and configured. If you built from source, use ./bin/port instead of port.

Commands

Use these top-level commands after you authenticate. Run port <command> --help for flags and options for each one.

Command	Purpose
port auth	Authenticate to organizations.
port api	Direct API operations (for example blueprints and entities).
port export	Export data from Port.
port import	Import data into Port.
port compare	Compare two Port organizations or export files.
port migrate	Migrate data between organizations.
port clear	Delete org resources in bulk.
port skills	Manage Port AI skill hooks and local skill sync.
port config	Manage CLI configuration.
port cache	Manage locally cached CLI data (for example port cache clear).
port version	Show the CLI version.

Examples

The following workflows show common ways to back up, compare, migrate, and clear Port organizations, and to sync AI skills into local coding tools.

Automated backups

Export your organization on a schedule and delete backups older than 30 days:

#!/bin/bash
DATE=$(date +%Y%m%d)
port export --output "backups/port-backup-$DATE.tar.gz"

# Keep only last 30 days
find backups/ -name "port-backup-*.tar.gz" -mtime +30 -delete

Compare organizations

By default, port compare compares all resource types (blueprints, actions, scorecards, pages, integrations, teams, users). Use --include to narrow the comparison.

Valid --include values: blueprints, actions, scorecards, pages, integrations, teams, users.

Basic

Compare two configured organizations:

port compare --source staging --target production

Show identifiers in the diff:

port compare --source staging --target production --verbose

Show a full field-level diff:

port compare --source staging --target production --full

Narrow scope

Compare only pages:

port compare --source staging --target production --include pages

Compare pages and blueprints together:

port compare --source staging --target production --include pages,blueprints

Export files

Compare two export files instead of live organizations:

port compare --source ./staging-backup.tar.gz --target ./prod-backup.tar.gz

Output

Output JSON for scripting:

port compare --source staging --target production --output json

Generate an interactive HTML report:

port compare --source staging --target production --output html --html-file report.html

CI

Fail the pipeline when any differences are found (exit code 1):

port compare --source staging --target production --fail-on-diff

Fail only when page differences are found:

port compare --source staging --target production --include pages --fail-on-diff

Clear organization resources

port clear deletes resources from a Port organization in bulk. It complements upsert-only import and migrate. Use it when you need to remove drift or rebuild a sandbox to a known state.

Several CLI commands include clear, but they target different scopes:

Command	Scope
port clear	Port org resources (API deletes).
port cache clear	Local CLI hooks, skills, and config.
port skills clear	Local synced skill files only.

Pass at least one resource-type flag. When you select more than one type, dependents are deleted before parents: entities → actions → scorecards → automations → pages → blueprints.

What to delete (pick at least one resource type)

Flag	Deletes
--entities	Entities.
--actions	Actions.
--scorecards	Scorecards.
--automations	Automations.
--pages	Root sidebar pages and folders (not nested children).
--blueprints	Blueprint definitions (system blueprints starting with _ are always skipped).

Control the delete (optional modifiers)

--blueprint (singular) is not the same as --blueprints (plural). Use --blueprint <identifier> to limit which blueprints are in scope after you choose a resource type above.

Flag	Purpose
--blueprint	Limit the delete to one or more blueprint identifiers (repeatable). Applies when you also pass --entities, --actions, --scorecards, or --blueprints.
--jq	Filter which entities are deleted (for example .properties.state == "archived").
--org	Target a specific organization.
--force	Skip the confirmation prompt (recommended in scripts).
--include-system-blueprints	Also clear entities, actions, and scorecards on system blueprints (_user, _team, and other _ identifiers).
--delete-protected-pages	Also delete root pages and folders whose identifiers start with _.

Limitations:

• Does not delete teams, users, integrations, or permissions.
• Not a full idempotent apply on its own - pair with import or compare.

Examples:

Delete all entities for a specific blueprint:

port clear --entities --blueprint service --force

Delete entities that match a JQ filter:

port clear --entities --blueprint aiSpec --jq '.properties.organization == "example-org"' --force

Reset a sandbox (supported config types), re-import, then verify:

port clear --entities --actions --scorecards --automations --pages --blueprints --force --org sandbox
port import --input ./config.tar.gz --org sandbox
port compare --source ./config.tar.gz --target sandbox --fail-on-diff

Common workflows:

• Sandbox rebuild: clear (supported types) → import → compare --fail-on-diff.
• Drift remediation: compare --output json to find extras, delete via scoped clear or port api, then import.
• Stage/prod: prefer import/migrate + compare for gating; avoid blanket clear.

User import

Users are imported as STAGED (pending activation) rather than being sent an invitation email. Existing users are updated with source data as-is.

See user status and controlling the initial status for how STAGED, DISABLED, and related statuses work.

Use --users-as-disabled to set non-admin new users to DISABLED instead (admin users are always staged):

# Import users as disabled (non-admins only)
port import --input backup.tar.gz --users-as-disabled

# Migrate users as disabled
port migrate --source-org prod --target-org staging --users-as-disabled

Pre-production testing

Promote a production export into staging, verify with compare, then migrate changes back when ready:

# Export from production
port export --output prod.tar.gz --org production

# Import to staging
port import --input prod.tar.gz --org staging

# Compare to verify changes
port compare --source prod.tar.gz --target staging --verbose

# Test changes in staging...

# When ready, migrate back
port migrate --source-org staging --target-org production

To rebuild a sandbox org to match a known config (when import alone cannot remove extra resources), clear supported types first, then import and verify:

port clear --entities --actions --scorecards --automations --pages --blueprints --force --org sandbox
port import --input ./config.tar.gz --org sandbox
port compare --source ./config.tar.gz --target sandbox --fail-on-diff

For a fuller multi-environment walkthrough, see Manage Port across environments.

Docker

Run export, import, and compare without installing the CLI locally. Mount a host directory when you need to read or write backup files:

# Export to a local directory
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

# Import from a local file
docker run --rm \
  -e PORT_CLIENT_ID="your-client-id" \
  -e PORT_CLIENT_SECRET="your-client-secret" \
  -v $(pwd)/output:/data \
  port-cli import --input /data/backup.tar.gz

# Compare two organizations
docker run --rm \
  -e PORT_CLIENT_ID="source-client-id" \
  -e PORT_CLIENT_SECRET="source-client-secret" \
  -e PORT_TARGET_CLIENT_ID="target-client-id" \
  -e PORT_TARGET_CLIENT_SECRET="target-client-secret" \
  port-cli compare --fail-on-diff

AI skill hooks

Planned deprecation

This skill-hook flow is planned for deprecation. You can keep using it for now. Port will introduce a new way of working with skills.

Sync skills from your Port organization into local AI coding tools (Cursor, Claude Code, Gemini CLI, OpenAI Codex, Windsurf, GitHub Copilot).

Synced and uploaded skills follow the Agent Skills specification: a skill directory with SKILL.md at the root, plus optional scripts/, references/, and assets/.

The default skills model supports sync, list, and search. Upload and publish commands require the labs versioned skills data model. Contact Port to enable it.

For concepts and authoring skills in Port, see Skills and the skills registry.

# One-time setup: choose tools and skill selection (saved to ~/.port/config.yaml)
port skills init

# Download skills to disk (after init, or pass --tool for a one-off sync)
port skills sync
port skills sync --tool Cursor --group operations
port skills sync --tool Cursor --tool "Claude Code" --tool Windsurf

# Scripts/CI: explicit flags or -y to select every option without prompts
port skills init -y
port skills init --tool Cursor --select-all-groups --select-all-ungrouped
port skills add --group my-group --skill my-skill --tool Cursor
port skills add integrations-overview
port skills add -y
port skills remove integrations-overview
port skills remove --tool Windsurf

# Check what's configured
port skills status

# Delete locally synced skill files only (hooks remain; skills re-sync on next session)
port skills clear

# Full cleanup: remove hooks, skill files, and config (everything Port CLI installed)
port cache clear

Query the catalog from the shell

Call the Port API from the shell, pipe JSON through jq, or update entities from a file:

port api call /blueprints | jq
port api entities update service payments --data ./payments.json