Portland CLI

Portland CLI giúp quản lý nhanh mapping local và expose dịch vụ ra internet qua control-plane + FRP/tunnels.

Hiện tại trong bản build hiện hành, CLI expose các lệnh:

• forward
• forward-list
• mesh
• kill
• export
• import
• start

1) Cài đặt CLI

npm install -g @huynhthuc/portland

Sau khi cài, kiểm tra:

portland --help

Hoặc khi chưa cài global:

npx @huynhthuc/portland --help

2) Cấu hình mặc định

• Config mặc định: ~/portland/config.json
• Hỗ trợ fallback đọc ~/.portland-proxy.json hoặc ~/.portland.json khi chưa có config mới.

Ví dụ cấu trúc config:

{
  "version": 1,
  "mappings": [
    {
      "name": "frontend",
      "listen": "127.0.0.1:3000",
      "target": "127.0.0.1:3000",
      "idleTimeout": 0,
      "killConflict": false,
      "killSignal": "SIGTERM",
      "active": true
    }
  ]
}

3) Các lệnh thường dùng

4.1 forward

Expose local service bằng sub-domain.

portland forward \
  -p 3000 \
  -s api-test \
  --base-url http://127.0.0.1:8787 \
  --protocol tcp \
  --admin-token <admin_token>

Kết quả trả về endpoint dạng ...:remote_port.

Các flag hay dùng:

• -p, --port: cổng service local
• -s, --sub-domain: tên public alias
• --protocol: tcp hoặc http (mặc định tcp)
• --public-domain: domain base hiển thị endpoint
• --public-port: ép port public cụ thể (nếu muốn)
• --machine-id / --machine-name: chọn machine
• --frpc-server, --frpc-server-port, --frpc-token: custom tunnel relay
• --skip-frpc-check, --skip-frpc-start: kiểm soát chạy frpc
• --json: in JSON
• --config: chọn file config mapping

4.2 forward-list

Quản lý tunnel frpc local.

portland forward-list
portland forward-list --active
portland forward-list --delete -n 1
portland forward-list --stop-all

Lưu ý: tunnels frpc sinh bởi forward thường tạo file log tại $(tmpdir)/portland/frpc.

4.3 mesh

Tương tác machine + ports (interactive).

portland mesh --base-url http://127.0.0.1:8787 --machine-name my-laptop

Flags quan trọng:

• --machine-name, --machine-id
• --labels
• --auto-select, --reconnect, --skip-join
• --auto-start-daemon
• --base-url, --admin-token, --machine-token
• --tailscale-socket, --tailscale-binary

4.4 start

Start proxy từ mapping đã lưu trong config.

portland start --active
portland start --name frontend

4.5 kill

Kill local process theo port, pid, hoặc cả hai.

portland kill --port 3000
portland kill --pid 12345
portland kill --port 3000 --pid 12345
portland kill --port 3000,3001 --pid 12345,12346
portland kill --port 3000 --signal SIGKILL

Flags quan trọng:

• --port: 1 port hoặc danh sách port phân tách bằng dấu phẩy
• --pid: 1 pid hoặc danh sách pid phân tách bằng dấu phẩy
• --signal: signal gửi tới process, mặc định SIGTERM

Ghi chú:

• Nếu truyền cả --port và --pid, CLI sẽ hợp nhất danh sách PID rồi kill một lần.
• CLI tự bỏ qua PID của chính tiến trình portland.
• Khi dùng SIGTERM, helper sẽ chờ ngắn rồi fallback SIGKILL nếu process chưa thoát.

4.6 export / import

Backup và restore mapping.

portland export -o mappings.json
portland import -i mappings.json

• export mặc định ghi vào file mappings.json cùng thư mục config nếu không truyền -o.
• import mặc định đọc từ mappings.json cùng thư mục config nếu không truyền -i.

6) Cách thao tác nhanh

# 1) Expose service
portland forward -p 3000 -s app --base-url http://127.0.0.1:8787 --admin-token <admin_token>

# 2) Kiểm tra tunnel đang chạy
portland forward-list

# 3) Giải phóng local port nếu bị chiếm
portland kill --port 3000

# 4) Dừng nhanh tất cả tunnel
portland forward-list --stop-all