Use when an AI agent or harness needs to operate the Portr CLI: authenticate a client, add users to teams, create HTTP/WebSocket/TCP/stub tunnels, run config-defined tunnels, inspect request logs, replay captured requests, or control tunnels through the local app-server API. This skill is compatible with Claude Code and Codex through vercel-labs/skills.
Use when an AI agent or harness needs to operate the Portr CLI: authenticate a client, add users to teams, create HTTP/WebSocket/TCP/stub tunnels, run config-defined tunnels, inspect request logs, replay captured requests, or control tunnels through the local app-server API. This skill is compatible with Claude Code and Codex through vercel-labs/skills.
Portr CLI
Use this skill to operate an installed portr binary from an AI agent, test harness, or automation script. Portr manages team membership, exposes local services through public HTTP/WebSocket or TCP tunnels, can serve stubbed templated responses, stores local HTTP request logs, can replay stored requests, and can run a local API for programmatic tunnel lifecycle control.
Agent Rules
Prefer portr --config <temp-config.yaml> ... for automation so user config, auth tokens, and local request logs are not accidentally changed.
Treat portr http, portr tcp, portr stub, portr start, and portr app-server as long-running processes. Keep their process/session IDs so the harness can stop them.
Prefer --json for portr logs and portr replay when a harness needs to parse output.
Use portr app-server for programmatic lifecycle management instead of scraping TUI output.
Do not overwrite ~/.portr/config.yaml, ~/.portr/db.sqlite, or auth tokens unless the user explicitly asks.
Do not create public tunnels for production services or sensitive local ports unless the user explicitly asks.
Treat a generated user password as a secret. Show it only in the requested command output and never repeat, log, or persist it elsewhere.
Adding a user changes server state. Confirm the email, team slug, and role from the user's request before running the command; use and only when those values were omitted.
default-team
member
If a command's flags are uncertain, run portr <command> --help against the installed binary.
--config, -c: YAML config path. Defaults to ~/.portr/config.yaml.
--help, -h: show help.
--version, -v: print version.
Commands:
portr help [command]: show general help or command-specific help.
portr auth set: configure client auth.
portr admin users add: add a user to a team.
portr config edit: open the default config in the OS editor.
portr config pull: replace the local tunnels and groups with the team template.
portr http: expose a local HTTP/WebSocket port.
portr tcp: expose a local TCP port.
portr stub: serve a templated response through a public HTTP tunnel without a local server.
portr start: start one or more tunnels from config.
portr logs: read local stored HTTP request logs.
portr replay: replay a stored HTTP request.
portr app-server: start a local HTTP API for harness-controlled tunnels.
Auth And Config
portr auth set --token <token> --remote <domain-or-url>
portr auth set -t <token> -r <domain-or-url>
portr config edit
portr config pull
--token, -t: Portr client secret token from the server/admin UI. Required.
--remote, -r: Portr server domain or URL. Required. Bare domains become HTTPS; localhost:* becomes HTTP unless a scheme is already provided.
config edit only edits the default config path. For harnesses, write a temp config file and pass --config.
config pull overwrites the default config's tunnels and groups with the team template configured in the admin dashboard, and fails if the team has no template. Everything else in the file, including secret_key and comments, is left alone. It also only acts on the default config path.
Uses the server_url and secret_key in the selected config. The credential must belong to an administrator of the target team; a superuser credential can target any team.
--team: target team slug. Defaults to default-team when omitted.
--role: member or admin. Defaults to member.
When GitHub auto signup is disabled, a newly created user receives an initial password and the CLI prints a Password: line.
When GitHub auto signup is enabled, new users are passwordless and the CLI omits the password line.
Existing users keep their credentials, so adding them to another team never resets or prints their password.
A missing default team is an error; do not create it implicitly.
