Caution
The Megaport CLI tool is currently an unsupported alpha, we're excited for feedback but please know that functionality and features may change drastically, and there may be bugs.
- Overview
- Installation
- Verifying Releases
- Getting Started
- Environment Support
- Configuration
- Documentation
- Shell Completion
- Architecture
- Available Commands
- Exit Codes
- Troubleshooting
- Additional Documentation
- Contributing
- Support
The Megaport CLI provides a command-line interface for managing Megaport resources and services. It allows users to interact with the Megaport API directly from their terminal.
Try the Megaport CLI directly in your browser - no installation required! The WASM version runs entirely in your browser and can be deployed with Docker.
👉 See WASM_README.md for deployment instructions
Quick Deploy:
./deploy.sh
# Then open http://localhost:8080Before using this CLI, please ensure you read and accept Megaport's Terms and Conditions and Acceptable Use Policy.
For API details, consult the Megaport API Documentation.
# Install using Go
go install github.com/megaport/megaport-cli@latest
# Verify installation
megaport-cli versionPre-built images are published to the GitHub Container Registry for linux/amd64 and linux/arm64 on every release:
# Run with the latest release
docker run --rm \
-e MEGAPORT_ACCESS_KEY=your_access_key \
-e MEGAPORT_SECRET_KEY=your_secret_key \
ghcr.io/megaport/megaport-cli:latest ports list
# Pin to a specific version
docker run --rm \
-e MEGAPORT_ACCESS_KEY=your_access_key \
-e MEGAPORT_SECRET_KEY=your_secret_key \
ghcr.io/megaport/megaport-cli:v0.4.7 locations list --metro "Sydney"- name: List Megaport ports
run: |
docker run --rm \
-e MEGAPORT_ACCESS_KEY=${{ secrets.MEGAPORT_ACCESS_KEY }} \
-e MEGAPORT_SECRET_KEY=${{ secrets.MEGAPORT_SECRET_KEY }} \
ghcr.io/megaport/megaport-cli:latest ports list -o jsonNote: This image runs the native CLI. For the browser-based interactive terminal, see WASM_README.md.
Release archives ship with SLSA build provenance attestations generated by GitHub Actions and logged to the Sigstore public transparency log. This lets you cryptographically verify that a downloaded archive was built by this repository's release workflow — independently of the existing GPG-signed SHA256SUMS file. Attestations are available on every release that includes this verification workflow; older releases verify only via SHA256SUMS.
Requires gh 2.49+:
# Download the archive from the GitHub release, then:
gh attestation verify megaport-cli_<version>_<os>_<arch>.zip \
--repo megaport/megaport-cliFor stronger guarantees, pin the verifying workflow and tag. This proves the archive was produced by the exact release workflow at the exact tag, defeating any attacker who only has write access to releases:
gh attestation verify megaport-cli_<version>_<os>_<arch>.zip \
--repo megaport/megaport-cli \
--signer-workflow megaport/megaport-cli/.github/workflows/release.yaml@refs/tags/v<version>A successful verification prints ✓ Verification succeeded! along with the workflow, commit SHA, and Rekor log entry that produced the attestation.
The existing SHA256SUMS file is GPG-signed, but both the binary and the sums file are served from the same GitHub release origin. Provenance attestations are anchored in a different trust root (GitHub's OIDC issuer + Sigstore's Fulcio CA + the public Rekor transparency log), so verifying both gives independent confirmation that the build pipeline itself was not tampered with.
To quickly begin using the Megaport CLI:
# Set up your environment variables
export MEGAPORT_ACCESS_KEY=your_access_key
export MEGAPORT_SECRET_KEY=your_secret_key
# Test your configuration
megaport-cli locations list
# Get help for any command
megaport-cli vxc --helpGenerate comprehensive documentation for all CLI commands:
# Generate documentation in the docs directory
megaport-cli generate-docs ./docsThe CLI supports shell completion for bash, zsh, fish, and PowerShell:
# Bash (Linux)
megaport-cli completion bash > /etc/bash_completion.d/megaport
# Bash (macOS with Homebrew)
megaport-cli completion bash > $(brew --prefix)/etc/bash_completion.d/megaport
# Zsh
megaport-cli completion zsh > "${fpath[1]}/_megaport"
# Fish
megaport-cli completion fish > ~/.config/fish/completions/megaport.fish
# PowerShell
megaport-cli completion powershell > megaport.ps1The CLI supports different Megaport environments:
- Production (default)
- Staging
- Development
Specify the environment using the --env flag or MEGAPORT_ENVIRONMENT variable.
The Megaport CLI uses a profile-based configuration system that securely stores API credentials and default settings.
- Profiles: Store multiple sets of credentials for different environments
- Secure Storage: Credentials stored with 0600 permissions in
~/.megaport/config.json - Default Settings: Configure preferred output format and other settings
# Create a profile
megaport-cli config create-profile myprofile --access-key xxx --secret-key xxx
# Switch active profile
megaport-cli config use-profile myprofile
# View current configuration
megaport-cli config viewSettings are applied in this order (highest to lowest precedence):
- Command-line flags (e.g.,
--access-key) - Environment variables (
MEGAPORT_ACCESS_KEY, etc.) - Active profile in config file
- Default settings in config file
| Variable | Description | Default |
|---|---|---|
MEGAPORT_ACCESS_KEY |
API access key (overrides active profile) | — |
MEGAPORT_SECRET_KEY |
API secret key (overrides active profile) | — |
MEGAPORT_ENVIRONMENT |
API environment: production, staging, development |
production |
MEGAPORT_CONFIG_DIR |
Override config file directory (default: ~/.megaport/) |
— |
For CI/CD pipelines or temporary usage, set these before running any command:
export MEGAPORT_ACCESS_KEY=your_access_key
export MEGAPORT_SECRET_KEY=your_secret_key
export MEGAPORT_ENVIRONMENT=productionFor complete documentation on configuration options, profile management, import/export functionality, and troubleshooting, see the Configuration Guide.
Note: Configuration profiles are only available in the standard CLI version. The WASM/browser version uses session-based authentication via the web UI login form.
The Megaport CLI is built using a Command Builder pattern that ensures consistent behavior across all commands. This modular approach makes the CLI easy to extend and maintain while providing a consistent user experience.
Key architectural components:
- Command Builder: Declarative command definitions for consistent behavior
- Flag Sets: Reusable sets of flags organized by resource type
- Output Formatters: Consistent data presentation across all commands
locations: List and search Megaport locationsports: Manage Megaport portsmcr: Manage Megaport Cloud Routersmve: Manage Megaport Virtual Edge instancesvxc: Manage Virtual Cross Connectsix: Manage Internet Exchange connectionspartners: List and search partner portsservicekeys: Manage service keysusers: Manage company usersmanaged-account: Manage partner managed accounts (sub-companies)billing-market: View and configure billing market detailsstatus: Show a dashboard of all resources
All commands support multiple output formats:
--output table(default)--output json--output csv--output xml
# List all locations
megaport-cli locations list
# List locations filtered by metro area
megaport-cli locations list --metro "San Francisco"
# Get details for a specific location
megaport-cli locations get LOCATION_ID --output json# List all ports
megaport-cli ports list
# List ports filtered by location ID and port speed
megaport-cli ports list --location-id 1 --port-speed 1000
# Get details for a specific port
megaport-cli ports get PORT_UID --output json
# Buy a new port
megaport-cli ports buy --interactive
megaport-cli ports buy --name "My Port" --term 12 --port-speed 10000 --location-id 123 --marketplace-visibility true
megaport-cli ports buy --json '{"name":"My Port","term":12,"portSpeed":10000,"locationId":123,"marketPlaceVisibility":true}'
megaport-cli ports buy --json-file ./port-config.json
# Buy a LAG port
megaport-cli ports buy-lag --interactive
megaport-cli ports buy-lag --name "My LAG Port" --term 12 --port-speed 10000 --location-id 123 --lag-count 2 --marketplace-visibility true
megaport-cli ports buy-lag --json '{"name":"My LAG Port","term":12,"portSpeed":10000,"locationId":123,"lagCount":2,"marketPlaceVisibility":true}'
megaport-cli ports buy-lag --json-file ./lag-port-config.json
# Update a port
megaport-cli ports update PORT_UID --interactive
megaport-cli ports update PORT_UID --name "Updated Port" --marketplace-visibility true
megaport-cli ports update PORT_UID --json '{"name":"Updated Port","marketplaceVisibility":true}'
megaport-cli ports update PORT_UID --json-file ./update-port-config.json
# Delete a port
megaport-cli ports delete PORT_UID --now
# Restore a deleted port
megaport-cli ports restore PORT_UID
# Lock a port
megaport-cli ports lock PORT_UID
# Unlock a port
megaport-cli ports unlock PORT_UID
# Check VLAN availability on a port
megaport-cli ports check-vlan PORT_UID VLAN_ID# List all MCRs
megaport-cli mcr list
# Get details for a specific MCR
megaport-cli mcr get MCR_UID --output json
# Buy a new MCR
megaport-cli mcr buy --interactive
megaport-cli mcr buy --name "My MCR" --term 12 --port-speed 10000 --location-id 123
megaport-cli mcr buy --name "My MCR" --term 12 --port-speed 10000 --location-id 123 --mcr-asn 65000 --diversity-zone "blue"
megaport-cli mcr buy --json '{"name":"My MCR","term":12,"portSpeed":10000,"locationId":123}'
megaport-cli mcr buy --json-file ./mcr-config.json
# Update an MCR
megaport-cli mcr update MCR_UID --interactive
megaport-cli mcr update MCR_UID --name "Updated MCR" --cost-centre "IT-123"
megaport-cli mcr update MCR_UID --json '{"name":"Updated MCR","costCentre":"IT-123"}'
megaport-cli mcr update MCR_UID --json-file ./update-mcr-config.json
# Delete an MCR
megaport-cli mcr delete MCR_UID --now
# Restore a deleted MCR
megaport-cli mcr restore MCR_UID
# Create a prefix filter list on an MCR
megaport-cli mcr create-prefix-filter-list MCR_UID --interactive
megaport-cli mcr create-prefix-filter-list MCR_UID --description "Block List" --address-family "IPv4" --entries '[{"action":"DENY","prefix":"10.0.0.0/8","ge":16,"le":24}]'
megaport-cli mcr create-prefix-filter-list MCR_UID --json '{"description":"Block List","addressFamily":"IPv4","entries":[{"action":"DENY","prefix":"10.0.0.0/8","ge":16,"le":24}]}'
megaport-cli mcr create-prefix-filter-list MCR_UID --json-file ./prefix-filter-config.json
# List all prefix filter lists for a specific MCR
megaport-cli mcr list-prefix-filter-lists MCR_UID
# Get details for a specific prefix filter list on an MCR
megaport-cli mcr get-prefix-filter-list MCR_UID PREFIX_FILTER_LIST_ID --output json
# Update a prefix filter list on an MCR
megaport-cli mcr update-prefix-filter-list MCR_UID PREFIX_FILTER_LIST_ID --interactive
megaport-cli mcr update-prefix-filter-list MCR_UID PREFIX_FILTER_LIST_ID --description "Updated Block List" --address-family "IPv4" --entries '[{"action":"DENY","prefix":"10.0.0.0/8"},{"action":"PERMIT","prefix":"192.168.0.0/16"}]'
megaport-cli mcr update-prefix-filter-list MCR_UID PREFIX_FILTER_LIST_ID --json '{"description":"Updated Block List","addressFamily":"IPv4","entries":[{"action":"DENY","prefix":"10.0.0.0/8"},{"action":"PERMIT","prefix":"192.168.0.0/16"}]}'
megaport-cli mcr update-prefix-filter-list MCR_UID PREFIX_FILTER_LIST_ID --json-file ./update-prefix-filter-config.json
# Delete a prefix filter list on an MCR
megaport-cli mcr delete-prefix-filter-list MCR_UID PREFIX_FILTER_LIST_ID# Get details for a specific MVE
megaport-cli mve get MVE_UID --output json
# Buy a new MVE
megaport-cli mve buy --interactive
# Buy a new MVE - Cisco example
megaport-cli mve buy --name "My Cisco MVE" --term 12 --location-id 67 --vendor-config '{"vendor":"cisco","imageId":1,"productSize":"large","mveLabel":"cisco-mve","manageLocally":true,"adminSshPublicKey":"ssh-rsa AAAA...","sshPublicKey":"ssh-rsa AAAA...","cloudInit":"#cloud-config\npackages:\n - nginx\n","fmcIpAddress":"10.0.0.1","fmcRegistrationKey":"key123","fmcNatId":"natid123"}' --vnics '[{"description":"Data Plane","vlan":100}]'
megaport-cli mve buy --json '{"name":"My Cisco MVE","term":12,"locationId":67,"vendorConfig":{"vendor":"cisco","imageId":1,"productSize":"large","mveLabel":"cisco-mve","manageLocally":true,"adminSshPublicKey":"ssh-rsa AAAA...","sshPublicKey":"ssh-rsa AAAA...","cloudInit":"#cloud-config\npackages:\n - nginx\n","fmcIpAddress":"10.0.0.1","fmcRegistrationKey":"key123","fmcNatId":"natid123"},"vnics":[{"description":"Data Plane","vlan":100}]}'
# Buy a new MVE - Aruba example
megaport-cli mve buy --name "My Aruba MVE" --term 1 --location-id 67 --vendor-config '{"vendor":"aruba","imageId":23,"productSize":"MEDIUM","accountName":"Aruba Test Account","accountKey":"12345678","systemTag":"Preconfiguration-aruba-test-1"}' --vnics '[{"description":"Data Plane"},{"description":"Control Plane"},{"description":"Management Plane"}]'
megaport-cli mve buy --json '{"name":"My Aruba MVE","term":1,"locationId":67,"vendorConfig":{"vendor":"aruba","imageId":23,"productSize":"MEDIUM","accountName":"Aruba Test Account","accountKey":"12345678","systemTag":"Preconfiguration-aruba-test-1"},"vnics":[{"description":"Data Plane"},{"description":"Control Plane"},{"description":"Management Plane"}]}'
# Buy a new MVE - Versa example
megaport-cli mve buy --name "My Versa MVE" --term 1 --location-id 67 --vendor-config '{"vendor":"versa","imageId":20,"productSize":"MEDIUM","directorAddress":"director1.versa.com","controllerAddress":"controller1.versa.com","localAuth":"SDWAN-Branch@Versa.com","remoteAuth":"Controller-1-staging@Versa.com","serialNumber":"Megaport-Hub1"}' --vnics '[{"description":"Data Plane"}]'
megaport-cli mve buy --json '{"name":"My Versa MVE","term":1,"locationId":67,"vendorConfig":{"vendor":"versa","imageId":20,"productSize":"MEDIUM","directorAddress":"director1.versa.com","controllerAddress":"controller1.versa.com","localAuth":"SDWAN-Branch@Versa.com","remoteAuth":"Controller-1-staging@Versa.com","serialNumber":"Megaport-Hub1"},"vnics":[{"description":"Data Plane"}]}'
# Update an existing MVE
megaport-cli mve update MVE_UID --interactive
megaport-cli mve update MVE_UID --name "Updated MVE Name" --cost-centre "New Cost Centre" --contract-term 24
megaport-cli mve update MVE_UID --json '{"name": "New MVE Name", "costCentre": "New Cost Centre", "contractTermMonths": 24}'
# Delete an MVE
megaport-cli mve delete MVE_UID --now
# List all available MVE images
megaport-cli mve list-images
# List MVE images filtered by vendor
megaport-cli mve list-images --vendor "Cisco"
# List MVE images filtered by product code
megaport-cli mve list-images --product-code "FORTINET456"
# List MVE images filtered by ID
megaport-cli mve list-images --id 1
# List MVE images filtered by version
megaport-cli mve list-images --version "2.0"
# List MVE images filtered by release image
megaport-cli mve list-images --release-image
# List all available MVE sizes
megaport-cli mve list-sizes# Get details for a specific VXC
megaport-cli vxc get VXC_UID --output json
# Buy a new VXC - Interactive mode.
megaport-cli vxc buy --interactive
# Flag mode - Basic VXC between two ports
megaport-cli vxc buy \
--a-end-uid "dcc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
--b-end-uid "dcc-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" \
--name "My VXC" \
--rate-limit 1000 \
--term 12 \
--a-end-vlan 100 \
--b-end-vlan 200
# Flag mode - VXC to AWS Direct Connect
megaport-cli vxc buy \
--a-end-uid "dcc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
--b-end-uid "dcc-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" \
--name "My AWS VXC" \
--rate-limit 1000 \
--term 12 \
--a-end-vlan 100 \
--b-end-partner-config '{"connectType":"AWS","ownerAccount":"123456789012","asn":65000,"amazonAsn":64512}'
# Flag mode - VXC to Azure ExpressRoute
megaport-cli vxc buy \
--a-end-uid "dcc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
--name "My Azure VXC" \
--rate-limit 1000 \
--term 12 \
--a-end-vlan 100 \
--b-end-partner-config '{"connectType":"AZURE","serviceKey":"s-abcd1234"}'
# Interactive mode
megaport-cli vxc update vxc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --interactive
# Flag mode - Basic updates
megaport-cli vxc update vxc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--name "New VXC Name" \
--rate-limit 2000 \
--cost-centre "New Cost Centre"
# Flag mode - Update VLANs
megaport-cli vxc update vxc-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--a-end-vlan 200 \
--b-end-vlan 300
# Delete a VXC
megaport-cli vxc delete VXC_UID# List all partner ports
megaport-cli partners list
# List partner ports filtered by product name and company name
megaport-cli partners list --product-name "AWS Direct Connect" --company-name "AWS"
# Interactive search for partner ports with prompts
megaport-cli partners find# List all service keys
megaport-cli servicekeys list
# Get details for a specific service key
megaport-cli servicekeys get SERVICE_KEY_UID --output json
# Create a new service key
megaport-cli servicekeys create --product-uid PRODUCT_UID --description "My Service Key" --max-speed 1000
# Update an existing service key
megaport-cli servicekeys update SERVICE_KEY_UID --description "Updated Description"# List all IXs
megaport-cli ix list
# Get details for a specific IX
megaport-cli ix get IX_UID --output json
# Buy a new IX
megaport-cli ix buy --interactive
megaport-cli ix buy --product-uid PORT_UID --name "My IX" --network-service-type "Los Angeles IX" --asn 65000 --mac-address "00:11:22:33:44:55" --rate-limit 1000 --vlan 100
megaport-cli ix buy --json '{"productUid":"PORT_UID","productName":"My IX","networkServiceType":"Los Angeles IX","asn":65000,"macAddress":"00:11:22:33:44:55","rateLimit":1000,"vlan":100}'
megaport-cli ix buy --json-file ./ix-config.json
# Update an existing IX
megaport-cli ix update IX_UID --interactive
megaport-cli ix update IX_UID --name "Updated IX" --rate-limit 2000
# Delete an IX
megaport-cli ix delete IX_UID# List all users in your company
megaport-cli users list
megaport-cli users list --active-only
megaport-cli users list --position "Technical Admin"
# Get details for a specific user
megaport-cli users get EMPLOYEE_ID
# Create a new user
megaport-cli users create --interactive
megaport-cli users create --first-name "John" --last-name "Doe" --email "john@example.com" --position "Technical Admin"
megaport-cli users create --json '{"firstName":"John","lastName":"Doe","email":"john@example.com","position":"Technical Admin"}'
# Update a user
megaport-cli users update EMPLOYEE_ID --interactive
megaport-cli users update EMPLOYEE_ID --first-name "Jane"
# Deactivate or delete a user
megaport-cli users deactivate EMPLOYEE_ID
megaport-cli users delete EMPLOYEE_ID --force
# View user activity
megaport-cli users activity# Show a dashboard of all active resources
megaport-cli status
# Include inactive/decommissioned resources
megaport-cli status --include-inactive
# Output as JSON
megaport-cli status -o json# Get current billing market configuration
megaport-cli billing-market get
megaport-cli billing-market get -o json
# Set billing market configuration
megaport-cli billing-market set --currency USD --language en \
--billing-contact-name "John Doe" --billing-contact-phone "+1234567890" \
--billing-contact-email "john@example.com" \
--address1 "123 Main St" --city "New York" --state "NY" \
--postcode "10001" --country US --first-party-id 1558# List all managed accounts linked to your partner account
megaport-cli managed-account list
megaport-cli managed-account list --account-name "Acme"
# Get details for a specific managed account
megaport-cli managed-account get COMPANY_UID ACCOUNT_NAME
# Create a new managed account
megaport-cli managed-account create --interactive
megaport-cli managed-account create --account-name "Acme Corp" --account-ref "REF-001"
megaport-cli managed-account create --json '{"accountName":"Acme Corp","accountRef":"REF-001"}'
# Update a managed account
megaport-cli managed-account update COMPANY_UID --account-name "New Name"| Exit Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage / validation error |
| 3 | Authentication error |
| 4 | API error |
| 5 | Cancelled by user |
If you see "401 Unauthorized", check:
- Your API credentials are correct:
megaport config view - Your active profile is set:
megaport config list-profiles - Environment variables aren't overriding your profile (unset
MEGAPORT_ACCESS_KEY/MEGAPORT_SECRET_KEYto use the profile)
Ensure the binary is in your PATH:
- Go install: Add
$(go env GOPATH)/binto your shell'sPATH - Manual install: Add the directory containing the binary to
PATH
If you see 429 errors, the Megaport API rate limit has been hit. Add delays between requests in automation scripts.
List operations fetch all resources. Use filters to narrow results:
megaport ports list --port-name "Sydney"megaport vxc list --a-end-uid <portUID>
Use --no-color if terminal colors cause display problems, or pipe output to a file.
This example shows setting up a complete cloud connection workflow:
# 1. Find available locations
megaport-cli locations list --metro "Sydney" --output json # Find the location ID from this output.
# 2. Create a port at your chosen location
megaport-cli ports buy --name "SYD-Port-1" --location-id 15 --port-speed 1000 --term 12
# 3. Find your cloud provider's connection point
megaport-cli partners list --company-name "AWS" --connect-type "AWS" --location-id 15
# 4. Create a VXC to connect your port to AWS
megaport-cli vxc buy --a-end-uid "port-xxxxxxxx" \
--name "AWS-Connection" \
--rate-limit 500 \
--a-end-vlan 100 \
--b-end-partner-config '{"connectType":"AWS","ownerAccount":"123456789012", "type":"private"}'The CLI includes comprehensive generated documentation in the docs folder:
- Index of all commands - Complete listing of all available commands
- Guides:
- AWS Direct Connect — step-by-step walkthrough for setting up AWS Direct Connect
- Multi-Cloud Connectivity — connect AWS, Azure, and GCP through a Megaport Cloud Router
- Portal to CLI Migration — transition from the Megaport Portal to the CLI
- Command References:
- Locations - Find and explore Megaport locations
- Ports - Manage physical ports
- VXC - Virtual cross connects between endpoints
- MCR - Megaport Cloud Router management
- MVE - Megaport Virtual Edge devices
- IX - Internet Exchange connections
- Partners - Cloud service provider connections
- Service Keys - Manage service keys for connections
- Users - Manage company users
- Managed Accounts - Partner sub-account management
- Billing Market - Billing contact and currency configuration
- Status - Resource dashboard
Each command page includes:
- Detailed descriptions
- All available flags and options
- Usage examples
- Links to related subcommands
You can regenerate this documentation at any time with:
megaport-cli generate-docs ./docsContributions via pull request are welcome. Familiarize yourself with these guidelines to increase the likelihood of your pull request being accepted.
All contributions are subject to the Megaport Contributor Licence Agreement.
The CLA clarifies the terms of the Mozilla Public Licence 2.0 used to Open Source this repository and ensures that contributors are explicitly informed of the conditions. Megaport requires all contributors to accept these terms to ensure that the Megaport Terraform Provider remains available and licensed for the community.
When you open a Pull Request, all authors of the contributions are required to comment on the Pull Request confirming acceptance of the CLA terms. Pull Requests cannot be merged until this is complete.
Megaport users are also bound by the Acceptable Use Policy.