Port Lifecycle — Megaport CLI

This tutorial walks through every stage of a Megaport Port — from finding a location to permanent decommission. By the end you'll know every port operation and when to use each one.

Lifecycle overview

ports buy

delete before live←

CONFIGURED

→

CANCELLED

fabric provisioning

LIVE

ports delete

DECOMMISSIONING

→restore→CONFIGURED

billing period ends

DECOMMISSIONED

Step 1 — Find a location

Ports are provisioned at specific data centres. Start by finding one near you or your cloud provider.

bash

# Browse all locations
megaport-cli locations list

# Filter by metro area
megaport-cli locations list --metro Sydney

# Only locations with MCR support (if you plan to add a cloud router later)
megaport-cli locations list --metro Sydney --mcr-available

Example output:

text

NAME                      COUNTRY    METRO   STATUS  MCR AVAILABLE
NextDC S1 Sydney          Australia  Sydney  ACTIVE  true
Equinix SY3 Sydney        Australia  Sydney  ACTIVE  true
Equinix SY4 Sydney        Australia  Sydney  ACTIVE  false
Global Switch Sydney West Australia  Sydney  ACTIVE  true
NEXTDC S2 Sydney          Australia  Sydney  ACTIVE  true

Note the ID by running with --output json to get the numeric location ID you'll need for --location-id:

bash

megaport-cli locations list --metro Sydney --output json | jq '.[] | {id, name}'

Step 2 — Provision a port

The same port can be purchased three ways. Choose the mode that fits your workflow.

Interactive

bash

megaport-cli ports buy --interactive

The CLI prompts for each parameter:

text

? Port name: Tutorial Port SYD-01
? Location ID (run 'locations list' to find IDs): 3
? Port speed [1000, 10000, 100000]: 10000
? Contract term in months [1, 12, 24, 36]: 12
? Marketplace visibility (make port visible to other Megaport customers)? No

Summary:
  Name:                  Tutorial Port SYD-01
  Location:              3 (NextDC S1 Sydney)
  Speed:                 10000 Mbps (10G)
  Term:                  12 months
  Marketplace visible:   false

? Confirm purchase? Yes

Port created: abc-1234-5678-def
Status: CONFIGURED

Flags

bash

megaport-cli ports buy \
  --name "Tutorial Port SYD-01" \
  --location-id 3 \
  --port-speed 10000 \
  --term 12 \
  --marketplace-visibility false

JSON

bash

megaport-cli ports buy --json '{
  "name": "Tutorial Port SYD-01",
  "locationId": 3,
  "portSpeed": 10000,
  "term": 12,
  "marketPlaceVisibility": false
}'

Or from a file:

bash

megaport-cli ports buy --json-file ./port-config.json

Parameter reference

Parameter	Values	Notes
`--name`	String, 1–64 chars	Shown in portal and invoices
`--port-speed`	`1000`, `10000`, `100000` Mbps	1G, 10G, or 100G
`--term`	`1`, `12`, `24`, `36` months	Longer terms = lower rates
`--marketplace-visibility`	`true` / `false`	`false` = private, not listed to other Megaport customers
`--diversity-zone`	e.g. `blue`, `red`	For redundant port pairs at the same location
`--cost-centre`	String	Billing label for cost allocation

💡

Save your Port UID

The output includes a Port UID (e.g. abc-1234-5678-def). Save it — every subsequent command uses it as the first argument or flag.

Step 3 — Check status

bash

# Full details
megaport-cli ports get <PORT-UID>

# Check provisioning status
megaport-cli ports status <PORT-UID>

# Watch status in real-time until it goes LIVE
megaport-cli ports status <PORT-UID> --watch

# See it in your list
megaport-cli ports list
megaport-cli ports list --port-name "Tutorial"

The port starts as CONFIGURED while Megaport provisions it on the fabric. It transitions to LIVE automatically — typically within a few minutes for a new port. Use --watch to auto-refresh until the transition completes.

Step 4 — Update the port

You can update a port's name, marketplace visibility, cost centre, or extend its term without any downtime.

bash

# Rename
megaport-cli ports update <PORT-UID> --name "Production Port SYD-01"

# Make it visible in the Megaport Marketplace
megaport-cli ports update <PORT-UID> --marketplace-visibility true

# Add a cost centre for billing reports
megaport-cli ports update <PORT-UID> --cost-centre "NET-001"

Step 5 — Lock and unlock

Locking a port prevents accidental deletion. Locked ports cannot be deleted until unlocked.

bash

# Lock — protects against accidental deletion
megaport-cli ports lock <PORT-UID>

# Unlock — allow changes again
megaport-cli ports unlock <PORT-UID>

💡

Lock production ports

Lock any port carrying live traffic. It takes one extra step to unlock before deleting, giving you a safety check against accidental delete commands.

Step 6 — Add resource tags

Tags are key-value pairs for organisation, cost allocation, and automation filtering.

bash

# Add tags (replaces all existing tags)
megaport-cli ports update-tags <PORT-UID> \
  --json '{"env":"production","team":"networking","project":"cloud-connect"}'

# View current tags
megaport-cli ports list-tags <PORT-UID>

⚠️

Tags are replaced, not merged

update-tags replaces the entire tag set. If you want to add a tag without losing existing ones, read the current tags first and include them all in your update.

Step 7 — Delete and restore

Port deletion is immediate — the previous "terminate at end of billing period" option is no longer supported by the API. Restoration is only possible during the brief decommissioning window before the port is fully removed from the fabric.

bash

megaport-cli ports delete <PORT-UID>

Safe delete — fail if VXCs are attached

Use --safe-delete to refuse deletion if the port still has attached VXCs:

bash

megaport-cli ports delete <PORT-UID> --safe-delete
# Error: port has 2 attached VXC(s) — delete them first or omit --safe-delete

Skip the confirmation prompt

bash

megaport-cli ports delete <PORT-UID> --force

Restore during the decommissioning window

If you deleted by mistake, restore while the port is still in DECOMMISSIONING:

bash

megaport-cli ports restore <PORT-UID>

Once the port reaches DECOMMISSIONED, restore is no longer possible.

⚠️

Delete is immediate and traffic-disrupting

The port and any attached VXCs are deleted right away. Run ports list-tags <PORT-UID> or vxc list --a-end-uid <PORT-UID> (and --b-end-uid for the other direction) first if you're unsure what's connected. For production ports, lock them (ports lock) so the delete fails until you intentionally unlock.

LAG ports — bundle multiple physical ports

A Link Aggregation Group (LAG) bundles 1–8 physical 10G or 100G ports at the same location into a single logical port. Use LAGs when one port can't carry the traffic, or when you need member-port redundancy. (A single-member LAG is uncommon but supported — it gives you the LAG framework so you can add member ports later without re-provisioning.)

Validate first

Dry-run the order to confirm pricing, member count, and location before you commit:

bash

megaport-cli ports validate-lag \
  --name "LAG SYD-PROD" \
  --location-id 3 \
  --port-speed 10000 \
  --lag-count 2 \
  --term 12 \
  --marketplace-visibility false

Buy

bash

megaport-cli ports buy-lag \
  --name "LAG SYD-PROD" \
  --location-id 3 \
  --port-speed 10000 \
  --lag-count 2 \
  --term 12 \
  --marketplace-visibility false

Or from JSON:

bash

megaport-cli ports buy-lag --json '{
  "name": "LAG SYD-PROD",
  "locationId": 3,
  "portSpeed": 10000,
  "lagCount": 2,
  "term": 12,
  "marketPlaceVisibility": false
}'

LAG parameter reference

Parameter	Values	Notes
`--port-speed`	`10000` or `100000` Mbps	Per-member speed (LAGs do not support 1G members)
`--lag-count`	1–8	Number of physical member ports in the bundle
`--term`	`1`, `12`, or `24` months	LAG does not support 36-month terms (single ports do)
`--name`, `--location-id`, `--marketplace-visibility`	Same as `ports buy`	All required
`--diversity-zone`, `--cost-centre`, `--resource-tags`	Optional	Same semantics as a single port

💡

Check VLAN availability before adding a VXC

Before attaching a VXC to any port (single or LAG), check whether the VLAN ID is free:

bash

megaport-cli ports check-vlan <PORT-UID> 100

This avoids the failure mode of provisioning a VXC against an in-use VLAN.

What's next?

Now that you can manage a port, connect it to something:

Connect to AWS — create a VXC to AWS Direct Connect
Connect to Azure — create a VXC to Azure ExpressRoute
Resource Types — understand what else you can connect to your port

💡

For Sales demos

Five minutes from command to live port — no data centre visits, no hardware lead times, no cross-connect orders. Run this in the browser terminal to show customers exactly how fast Megaport provisions infrastructure.