port-cli

README

Port CLI

A modular command-line interface for Port that enables data import/export, organization migration, and API operations using a pluggable module architecture.

Features

• 📤 Export: Backup Port data (blueprints, entities, scorecards, actions, teams, automations, pages, integrations)
• 📥 Import: Restore data from backups
• 🔄 Migrate: Transfer data between Port organizations
• 🔌 API Operations: Direct CRUD operations on Port resources

Installation

Quick Install (Recommended)

Linux/macOS:

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

This will download and install the latest release binary to /usr/local/bin (or ~/.local/bin if you don't have write permissions).

Verify installation:

port --version

Binary Releases

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

Build from Source

For development or if you need the latest unreleased code:

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

Note: When building from source, use ./bin/port instead of port in commands. For installed binaries, use port directly.

See INSTALL.md for detailed installation instructions.

Quick Start

1. Configure Credentials

Run port config --init to create a configuration file at ~/.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

Or use environment variables:

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

2. Run Commands

# Export data
port export --output backup.tar.gz

# Import data
port import --input backup.tar.gz

# Migrate between organizations
port migrate --source-org prod --target-org staging

# API operations
port api blueprints list

Note: If you built from source instead of installing, use ./bin/port instead of port in the commands above.

Commands

• port export - Export data from Port
• port import - Import data to Port
• port migrate - Migrate data between organizations
• port api - Direct API operations (blueprints, entities)
• port config - Manage configuration
• port version - Show version

Development

Go CLI Development

# Build
make build

# Run tests
make test

# Format code
make format

# Lint
make lint

Project Structure

port-cli/
├── cmd/port/              # Go CLI entry point
├── internal/              # Go implementation
│   ├── api/              # API client
│   ├── config/           # Configuration management
│   ├── commands/         # CLI commands
│   ├── modules/          # Business logic modules
│   └── output/           # Output formatters
├── go.mod                # Go dependencies
└── Makefile              # Go build

Configuration

Configuration File

Create ~/.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
    
  staging:
    client_id: staging-client-id
    client_secret: staging-client-secret
    api_url: https://api.getport.io/v1

Environment Variables

PORT_CLIENT_ID          # Port API client ID
PORT_CLIENT_SECRET      # Port API client secret  
PORT_API_URL           # Port API URL (optional)
PORT_CONFIG_FILE       # Path to config file
PORT_DEFAULT_ORG       # Default organization name
PORT_DEBUG             # Enable debug mode

Precedence: CLI args > env vars > config file > defaults

Examples

Automated Backups

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

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

Pre-Production Testing

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

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

# Test changes in staging...

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

Contributing

See CONTRIBUTING.md for development guidelines.

Release Process

See RELEASE.md for release procedures.

License

MIT License - see LICENSE

References

• Port Documentation
• Port API Reference