CLI reference

Applies to: ✓ Mode 1 · ✓ Mode 2 · ✓ Mode 3

A companion to --help, not a replacement — every command prints its own full help, and this page groups the surface so you can find things. Three binaries ship in skimasque-cli:

Most flags also read a SKIMASQUE_* environment variable (noted where it matters); secrets are marked so --help hides their values.

skimasque

Policy, locally (no network)

check / explain / why / learn take identity flags — --repository owner/name, --branch <b> (or --ref refs/heads/<b>), --workflow, --environment, --actor, --organization — plus --app <name> and --transport tcp|udp (default tcp). Policy source is --policy-dir (default .masque/policies) or repeatable --policy-file.

$ skimasque why db.internal:5432 --app psql --repository acme/web --branch main

Sign in to a control plane

The credential file lives at $SKIMASQUE_CONFIG_HOME, else $XDG_CONFIG_HOME/skimasque/, else ~/.config/skimasque/ (Unix) / %APPDATA%\skimasque\ (Windows), mode 0600.

Manage an organisation (needs skimasque login)

--org is inferred when you belong to exactly one.

Give a coding agent access (needs skimasque login)

The lifetime defaults to 30 minutes and is capped at 4 hours. See agents.md for the model and for sandboxing.

Run a gateway or open a tunnel

• skimasque gateway <args…> execs skimasque-server with the args — see below.
• skimasque connect <DEST> [client args…] execs skimasque-client … connect --target <DEST>, bridging the tunnel to stdin/stdout (an SSH ProxyCommand, a pipeline). Uses the client default gateway or an explicit --proxy; without an explicit credential, the client can mint one from your signed-in session. Automatic customer-gateway discovery is not implemented.

Run a command with access

skimasque exec [--policy NAME] [--app NAME] [--gateway HOST[:PORT]]
               [--forward [LOCAL_PORT:]HOST:PORT]... [--org ORG] [--quiet]
               [--auth-token T | --github-oidc --oidc-audience AUD]
               [--ca PEM | --insecure] -- COMMAND [ARGS...]

Opens a gateway session, starts an HTTP CONNECT proxy and a SOCKS5 relay on loopback, and runs COMMAND with HTTPS_PROXY/HTTP_PROXY (HTTP CONNECT), ALL_PROXY (socks5h://) and NO_PROXY=localhost,127.0.0.1,::1 set. Access ends when the command exits.

The HTTP_PROXY front end tunnels CONNECT (HTTPS and other TLS) and carries plain http:// requests too: it opens a tunnel to the URL's host and port, sends the request to the origin with Connection: close, and relays the reply. One connection carries one request, so no keep-alive; a request that is not a CONNECT or an absolute-form http:// URL is refused (405). Other TCP is reached through ALL_PROXY (socks5h://) or a --forward.

The loopback listeners are not authenticated: while the command runs, any process on the machine can use the proxy and forward ports with your identity, the same exposure as ssh -L. Don't run exec on a shared host you don't trust.

With a skimasque login session exec checks your access with the control plane first and refuses to start when --policy does not apply or every --forward would be denied. Exit status is the command's; 125 when exec fails before starting it, 126/127 when it cannot be run. Ctrl-C, SIGTERM or SIGHUP before the command starts stops exec with 128 + signal (130 for Ctrl-C); once it runs, Ctrl-C goes to the command and SIGTERM/SIGHUP are passed on to it.

On Windows a bare command name is resolved like cmd.exe does it: each PATH directory in order, trying each PATHEXT extension, so skimasque exec -- npm ci runs npm.cmd.

skimasque exec --policy production -- terraform apply
skimasque exec --forward 15432:db.prod:5432 -- psql -h 127.0.0.1 -p 15432

skimasque-server

--listen <ADDR> (default 0.0.0.0:4433; use 0.0.0.0:443 in production). Repeat -v for more logging — the ACME lifecycle and the policy audit trail show at the default level.

TLS — pick one

Identity

Policy

--policy-dir <DIR> or repeatable --policy-file <PATH> — without a source the gateway applies only the address floor. --policy-reload swaps the set on a file change (or SIGHUP) with no dropped tunnel; --policy-reload-interval (5s). --policy-observe logs what policy would decide but allows every tunnel (feeds skimasque policy learn). --audit-log <PATH> appends a JSON-lines record of every decision (conflicts with --policy-observe).

Control plane (instead of local policy)

Address floor, limits, ops

• --allow-cidr <CIDR> (repeatable) — open one private/loopback range; --allow-private opens all of them; --allow-port <PORT> (repeatable) restricts to named ports.
• Resource caps, each 0 to disable: --max-connections (1024), --max-connection-rate / --max-connection-burst (50 / 200), --max-source-connection-rate / -burst (20 / 60), --max-exchange-rate / -burst (10 / 30), --max-concurrent-requests (1024), --max-tunnels-per-connection (256), --tunnel-idle-timeout (120s).
• --no-connect-tcp — UDP only. TCP tunnels (what a SOCKS front end needs for curl / git / databases) are served by default; this refuses them.
• --metrics-listen <ADDR> — /healthz, /readyz, Prometheus /metrics on a plain-HTTP listener; keep it on a private interface.
• --shutdown-grace <DUR> — how long in-flight tunnels get after SIGTERM before the endpoint closes (default 10s).
• --authority <HOST[:PORT]> / --template <T> — the URI Template served (defaults from --hostname).

skimasque-client

skimasque-client [connection flags] <proxy | socks5 | connect | probe>

skimasque-client capabilities --json reports versioned frontend capabilities without contacting a gateway or reading credentials.

Connection flags

On Linux, proxy --tun-interface NAME also forwards packets from an existing user-owned TUN with MTU 1280 using embedded tun-rs and a smoltcp-based stack. The Action owns route/DNS setup; the client attaches without configuring it. Native readiness includes tun_interface, and Linux capabilities include proxy-tun-v1. TCP and UDP flow directly through the shared MASQUE session; there is no external adapter or intermediate SOCKS hop for native traffic. ICMP, IP fragmentation and arbitrary IP protocols are unsupported. UDP payloads must fit both the interface MTU and the MASQUE datagram limit.

Subcommands

$ skimasque-client --proxy gw.example.com --github-oidc \
    --oidc-audience https://gw.example.com --app psql \
    proxy --ready-file /tmp/skimasque-ready.json

For proxy-aware tools, set both uppercase and lowercase HTTP_PROXY and HTTPS_PROXY to http://127.0.0.1:8080, ALL_PROXY to socks5h://127.0.0.1:1080, and NO_PROXY to localhost,127.0.0.1,::1. HTTPS uses CONNECT through the HTTP listener; the SOCKS hostname is resolved at the gateway. These variables do not intercept tools using raw sockets.

The optional readiness file is created atomically after authentication and both binds. It contains schema 1, pid, actual http/socks addresses and the connected gateway. Existing files are never overwritten. Unix SIGTERM/Ctrl-C and normal exit remove readiness; forced kills can leave a stale file, so callers must also verify process identity and health. OIDC credentials refresh in place: new tunnels use the replacement and existing tunnels continue. Gateway closure terminates the frontend.

The connect Action supervises this mode. Its transparent mode additionally routes configured private TCP/UDP and DNS through a TUN adapter on supported dedicated Ubuntu runners, without global proxy variables. It requires explicit CIDRs and private DNS settings, both families when needed, and matching client/Action releases.