> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> The pgw commands and flags that run the gateway and manage it through the admin API.

Every command except `init`, `serve`, and `version` calls the admin API. Such a command fails when the API doesn't answer within 30 seconds, or 3 minutes for `pgw config sync`.

## Commands

| Command | Description |
| - | - |
| `pgw init [--hostname <host>] [--force]` | Writes `.env`, `config.yaml`, and `tenant.yaml` to the current folder, to try pgw on your own computer. See [pgw init](#pgw-init). |
| `pgw serve [--config <file>]` | Runs the gateway. Without `--config`, it reads `config.yaml` from the current folder when that file exists. `PGW_*` environment variables override the file. At startup it logs which file it read, or `none`. When `.env` supplies the master key, `serve` refuses to start if the file's group or other users have any access to it. |
| `pgw version` | Prints the version and commit, such as `pgw v0.4.0 (9d1b63c)`. |
| `pgw bootstrap [--name <name>]` | Creates the first tenant, named `default` unless you give `--name`, and prints its API key. Fails with `409` and `already bootstrapped` once the database holds a tenant. Needs the server's token in `PGW_BOOTSTRAP_TOKEN` or `--token`. When the current folder has a `.env` file, `bootstrap` also saves the key there as `PGW_API_KEY`. If other users can read `.env`, `bootstrap` first makes it readable by its owner only. Standard output carries only the key. |
| `pgw app create <flags>` | Creates an App, and prints it without its credentials. See [pgw app create](#pgw-app-create). |
| `pgw app list` | Lists the Apps without their credentials. A web App shows `vapid_public_key`. |
| `pgw app set-name --id <id> --name <name>` | Sets the name, 1 to 64 characters, that log lines show for the App. `--name ""` removes it, and log lines show the bundle ID. |
| `pgw app set-delivery-mode --id <id> --mode <mode>` | Sets the App's delivery mode: `provisional`, `always_push`, or `default` to use the gateway default. |
| `pgw app set-managed-refresh-push --id <id> --value <value>` | Sets whether pgw sends the App's managed mode devices a refresh push: `on`, `off`, or `default` to use the gateway default. |
| `pgw app export-vapid-key --id <id> [--out <file>]` | Writes a web App's VAPID private key in PEM, for a backup. With `--out`, pgw creates the file with mode `0600`, fails if it exists, and prints nothing. Anyone with the key can send pushes to the tenant's browsers. |
| `pgw upstream create <flags>` | Creates an upstream. See [pgw upstream create](#pgw-upstream-create). |
| `pgw upstream update --id <id> <flags>` | Changes the upstream fields whose flags you give, and keeps the others. See [pgw upstream update](#pgw-upstream-update). |
| `pgw upstream delete --id <id> [--force]` | Deletes an upstream, with its users and domains. While bindings use it, the API refuses with `409`. `--force` deletes its bindings too. The PBX keeps their registrations until they expire, and pgw refuses the calls that the PBX sends to them meanwhile. |
| `pgw user create --upstream <id> --username <name> [--domain <domain>] [--auth-username <name>]` | Adds a SIP account to a managed upstream. pgw checks the account itself and registers it at the PBX. Apps authenticate to pgw as `--username`. On an upstream with domains, `--domain` is required: the domain that the user's apps register to, which is the upstream's host or a name that its domains serve. `1001` at two domains is two users. Set `--auth-username` when the PBX knows the account by another name, and pgw answers the PBX with it. The password comes from `PGW_USER_PASSWORD`, so it stays out of the command line. An upstream whose users come from Kamailio refuses it with `409`. |
| `pgw user list --upstream <id>` | Lists an upstream's users, without passwords. An upstream whose users come from Kamailio refuses it with `409`. |
| `pgw user set --id <id> [--enabled=true or false] [--password] [--auth-username <name>]` | Turns a user on or off, sets its password from `PGW_USER_PASSWORD` with `--password`, or changes its auth username. `--auth-username ""` clears it. Give at least one of the three flags. |
| `pgw user delete --id <id>` | Deletes a user. |
| `pgw user revoke --upstream <id> <user>[@<domain>]` | Removes a user's registrations on a managed upstream at once, unregisters them at the PBX, and prints `revoked <n> bindings`. The user stays. On an upstream with domains, or a Kamailio upstream with `use_domain`, name the domain, and pgw removes only the registrations to that domain. Elsewhere, name the user alone. pgw splits the argument at the last `@`. Put a user that starts with `-` after `--`. |
| `pgw config export [--out <file>]` | Writes the tenant's apps, upstreams, and managed mode users as YAML, without secrets. With `--out`, pgw writes the file and prints nothing. A new file gets mode `0600`, and an existing file keeps its mode. |
| `pgw config sync <file> [--dry-run] [--prune] [--yes]` | Makes the tenant match the YAML file, and prints the plan. Without `--prune`, it deletes nothing. See [pgw config sync](#pgw-config-sync). |
| `pgw binding list` | Lists every binding of the tenant. `flow_alive` shows whether the device is connected to pgw, and `user_agent` names the device's app. |
| `pgw binding delete --binding <key>` | Removes the binding, and on a managed mode upstream its registration at the PBX. |
| `pgw binding test-push --binding <key>` | Sends the device a silent push, which the app doesn't show, and prints the push service's answer. The API refuses with `409` when the binding has no push token that takes a silent push: no push parameters, a dead token, or no remote token on iOS. |
| `pgw cert reload` | Makes the server load its certificate and key files again, as `SIGHUP` does. Open app connections stay. Prints `certificate reloaded; it expires at <time>`. Needs the server's token in `PGW_BOOTSTRAP_TOKEN` or `--token`. |
| `pgw ban list` | Lists the source addresses that pgw refuses REGISTERs from after too many refused credentials. Needs the server's token in `PGW_BOOTSTRAP_TOKEN` or `--token`. |
| `pgw ban lift --source <address>` | Lifts the ban of a source address, clears its count of refused credentials, and prints `ban lifted for <address>`. The address is an IP address or an IPv6 /64 prefix. An IPv6 address lifts the ban of its /64. Needs the server's token in `PGW_BOOTSTRAP_TOKEN` or `--token`. |

Most commands that call the admin API print its answer as JSON. `bootstrap` prints the API key, `app export-vapid-key` prints the key in PEM, `cert reload`, `ban lift`, and `user revoke` print one line, `config export` prints YAML, `config sync` prints its plan, and the `delete` commands print nothing.

A command exits with status 0 when it succeeds, 1 when it fails, and 2 when its arguments or flags are wrong. pgw writes each error to standard error, after `pgw: `:

```text theme={null}
pgw: POST /api/v1/bootstrap: 409 Conflict: already bootstrapped
```

## The .env file

Every command except `pgw init`, `pgw version`, and an unknown command reads the `PGW_` lines of `.env` in the current folder, as if you had exported them. So a `PGW_KAMAILIO_PASSWORD` line in `.env` replaces the stored password on every `pgw upstream update`, and a `PGW_USER_PASSWORD` line sets the password on every `pgw user create`. After `pgw bootstrap`, `.env` also holds `PGW_API_KEY`.

A variable that your shell sets to a non-empty value wins over `.env`, and pgw warns `your shell overrides <name> from .env`. The master key and the master key file count as one setting, so when the shell sets either, pgw reads neither from `.env`.

## pgw init

`pgw init` writes three files to the current folder and prints the commands to run next. It doesn't read `.env`, and it prints no secret.

| File | Mode | Content |
| - | - | - |
| `.env` | `0600` | `PGW_MASTER_KEY`, a new random master key, and `PGW_BOOTSTRAP_TOKEN`, a new random token. |
| `config.yaml` | `0644` | Every setting. `hostname` and `data_dir: ./data` are set, and the others are commented out with their defaults. To change one, remove the `# ` and edit the value. `pgw serve` reads the file from this folder. |
| `tenant.yaml` | `0644` | One upstream with the placeholder host `<pbx-host>`, and commented examples of an Android, an iOS, and a web app, a managed upstream, and an upstream whose users come from Kamailio. Edit it, then run `pgw config sync tenant.yaml`. |

| Flag | Default | Description |
| - | - | - |
| `--hostname <host>` | The address of this computer on your network | The DNS name or IP address that phones and PBXs use to reach pgw. Without the flag, pgw asks the routing table for the address that it uses toward other computers, without sending a packet. When it finds none, pgw writes `127.0.0.1` and warns you to set `hostname` in `config.yaml`. |
| `--force` | Off | Replaces `.env`, `config.yaml`, and `tenant.yaml` when they exist. The new `.env` has mode `0600`. `--force` replaces `.env` whole, so it also deletes lines that other tools keep there. |

Without `--force`, `pgw init` writes nothing and fails when any of the three files exists. The error names the files, and when `.env` is one of them, it says that `--force` replaces `.env` whole.

Even with `--force`, `pgw init` fails when `data/pgw.db` exists or the `data_dir` that `config.yaml` names holds a `pgw.db`, because a new master key can't open that database. The error names the folder. Delete it to start over. `pgw init` ignores a `config.yaml` that it can't read.

## Flags for commands that call the API

| Flag | Default | Description |
| - | - | - |
| `--admin <url>` | `http://127.0.0.1:8080` | The admin API, an `http` or `https` URL. pgw warns when the URL uses `http` to a host other than `localhost` or a loopback address. |
| `--key <key>` | `PGW_API_KEY` | The tenant API key. Set `PGW_API_KEY` instead, to keep the key out of the process list. `bootstrap`, `cert`, and `ban` don't use it. |
| `--token <token>` | `PGW_BOOTSTRAP_TOKEN` | The token that the server was started with. Only `bootstrap`, `cert reload`, `ban list`, and `ban lift` take it, in place of the API key. Set `PGW_BOOTSTRAP_TOKEN` instead, to keep the token out of the process list. |

## pgw app create

| Flag | Platform | Description |
| - | - | - |
| `--platform` | All | `ios`, `android`, or `web`. A tenant can have one web App. |
| `--bundle-id` | All | The iOS bundle ID or the Android package name. For a web App, any label. Required. |
| `--name` | All | A name for the App, such as `Acme Phone`, 1 to 64 characters. Log lines show it. Without it, they show the bundle ID. |
| `--apns-team-id`, `--apns-key-id` | iOS | The Apple team ID and the APNs key ID. |
| `--apns-key-file` | iOS | The APNs `.p8` key file. |
| `--apns-environment` | iOS | `production` (default) or `sandbox`. Builds run from Xcode use `sandbox`. |
| `--fcm-project-id` | Android | The Firebase project ID. pgw sends pushes to this project. |
| `--fcm-project-number` | Android | The Firebase project number. Set it for an app that sends the project number in `pn-param` instead of the project ID. |
| `--fcm-service-account-file` | Android | The Firebase service account key file. |
| `--vapid-subject` | Web | A `mailto:` or `https:` URI that push services can use to contact you. |
| `--vapid-key-file` | Web | A P-256 private key in PEM to use as the VAPID key, such as one that `pgw app export-vapid-key` wrote. Without it, pgw generates a key. |
| `--delivery-mode` | All | `provisional` or `always_push`. Defaults to the gateway setting. |
| `--managed-refresh-push` | iOS, Android | `on` or `off`: whether pgw sends the App's managed mode devices a refresh push. Defaults to the gateway setting. |

## pgw upstream create

| Flag | Default | Description |
| - | - | - |
| `--name` | None | A name for the upstream. Required. |
| `--host` | None | The PBX host name or IP address, without a port. pgw sends REGISTERs and calls to this address. A REGISTER finds its upstream by its Request-URI host, so this is also a SIP domain that apps can register to. The binding's address of record is the user and host of the REGISTER's To URI. The host can't change later. |
| `--domains` | None | Comma-separated SIP domains, besides `--host`, that apps register to through this upstream. You can't combine it with `--user-source kamailio`. An entry is a DNS name, such as `acme.example.com`, or `*.` and a DNS name, such as `*.example.com`, which matches every name under `example.com` at any depth but not `example.com` itself. A REGISTER goes to the upstream whose host or domain equals its Request-URI host, or else to the upstream with the longest wildcard that matches it. Each host and domain belongs to one upstream across the pgw install, and none can overlap a name of another tenant. A wildcard can't cover a single label, such as `*.lan`, or a public suffix, such as `*.com`. pgw stores domains in lower case. |
| `--port` | `5060` | The PBX port, from 1 to 65535. |
| `--transport` | `udp` | `udp` or `tcp`. pgw doesn't connect to PBXs over TLS. With `tcp`, the Path that pgw sends the PBX asks it to send calls to pgw over TCP. |
| `--max-expires` | `3600` | The registration expiry, in seconds, that pgw asks the PBX for. When the PBX answers `423 Interval Too Brief` with a longer minimum, pgw asks for that minimum, up to one day, until it restarts. |
| `--invite-source-cidrs` | The host, when `--host` is an IP address | Comma-separated CIDR prefixes that may send INVITEs. Required when `--host` is a DNS name. A change applies at once. |
| `--strict-path` | On | Refuses a registration when the PBX's answer doesn't keep pgw's Path. The PBX then never sends calls past pgw. To turn it off, give `--strict-path=false`. |
| `--mode` | `passthrough` | `passthrough`: the PBX checks each app's password. `managed`: pgw checks it against its users and keeps the registration at the PBX itself. You can't change the mode later. |
| `--keepalive-seconds` | `30` | Sends the PBX an OPTIONS at this interval, from 5 to 3600 seconds, and reports whether it answers in `pgw_upstream_up`. The OPTIONS also keeps a NAT, a cloud provider's idle timeout, or a Linux connection tracker from dropping the path to the PBX. `0` sends none. |
| `--realm` | The user's domain on an upstream with domains or a Kamailio upstream with `use_domain`, else `--host` | Managed mode only. The digest realm that pgw challenges apps with, at most 128 bytes. Set it when apps were set up with the PBX's own realm. It can't change later. |
| `--contact-strategy` | `path`, or `masquerade` in managed mode | `path` sends the PBX the app's Contact and a Path to pgw. `masquerade` sends the PBX pgw's own address as the Contact, for a PBX without Path support. `--strict-path` then has no effect. Managed mode allows only `masquerade`. It can't change later. |
| `--managed-registration` | The gateway setting, `per_user` unless changed | Managed mode only. `per_user` registers one contact per user at the PBX, and pgw rings every device of the user itself, so the PBX needs a free contact per user rather than one per device. `per_device` registers each device, so the PBX sees and limits devices. |
| `--user-source` | `pgw` | Managed mode only. `pgw` reads the users that you add with `pgw user create`. `kamailio` reads the subscribers in a Kamailio database, which the `--kamailio-` flags name, and needs the database user's password in `PGW_KAMAILIO_PASSWORD`. pgw connects to the database and reads its tables before it creates the upstream. It can't change later. |
| `--app-auth` | `digest` | How apps authenticate their REGISTER to pgw. `digest` uses the user's password. `bearer` uses an access token that your identity service signs, in an `Authorization: Bearer` header. `both` accepts either. `bearer` and `both` need managed mode and the three `--bearer-` flags. |
| `--bearer-issuer` | None | The token issuer. pgw compares it byte for byte with the token's `iss` claim. |
| `--bearer-audience` | None | The audience that the token's `aud` claim must hold. |
| `--bearer-jwks-url` | None | The `https` URL of the issuer's JSON Web Key Set, which holds the keys that sign the tokens. It can't hold a user name or password. |
| `--kamailio-driver` | None | `mysql`, which also reads MariaDB, or `postgres`. |
| `--kamailio-host` | None | The database's host name or IP address. pgw connects over TCP only. |
| `--kamailio-port` | `3306` for `mysql`, `5432` for `postgres` | The database's port. |
| `--kamailio-user` | None | A database user with only `SELECT` on the subscriber and domain tables. |
| `--kamailio-database` | None | The database name. |
| `--kamailio-tls` | `verify` | `verify` uses TLS and checks the server's certificate against the system's roots and `--kamailio-host`. `require` uses TLS without that check, for a server with a self-signed certificate. `off` uses plain TCP. |
| `--kamailio-use-domain` | On | Looks subscribers up by username and domain, as Kamailio's `use_domain` does, and accepts registrations to the domains in the domain table. With `--kamailio-use-domain=false`, pgw looks them up by username alone. It can't change later. |
| `--kamailio-subscriber-table`, `--kamailio-username-column`, `--kamailio-domain-column`, `--kamailio-password-column`, `--kamailio-ha1-column`, `--kamailio-domain-table`, `--kamailio-domain-table-column` | Kamailio's own names | The tables and columns that pgw reads, when your schema renames them. `--kamailio-password-column ""` or `--kamailio-ha1-column ""` makes pgw read only the other column. |

## pgw upstream update

`pgw upstream update --id <id>` takes these flags, with the meanings in [pgw upstream create](#pgw-upstream-create): `--name`, `--port`, `--transport`, `--max-expires`, `--invite-source-cidrs`, `--domains`, `--keepalive-seconds`, `--strict-path=true` or `--strict-path=false`, `--managed-registration`, `--app-auth`, the `--bearer-` flags, and the `--kamailio-` flags other than `--kamailio-use-domain`. It changes only the fields whose flags you give, and fails with `set at least one field to change` when you give none.

* `--managed-registration` takes `per_user`, `per_device`, or `default` to use the gateway setting.
* `--app-auth digest` removes the stored issuer, audience, and key set URL, and refuses `--bearer-` flags. A change to `bearer` or `both` needs all three `--bearer-` values, given or stored.
* When `PGW_KAMAILIO_PASSWORD` is set, it replaces the database password, even without a flag. When a Kamailio setting or the password changes, pgw connects to the database and reads its tables first, as it does on a create.
* `--invite-source-cidrs ""` removes every prefix. Only an upstream whose host is an IP address accepts it.
* `--domains` replaces the list of domains, and `--domains ""` removes them all.
* The host, mode, contact strategy, realm, user source, and `--kamailio-use-domain` can't change. To change one, delete the upstream and create it again.

## pgw config sync

`pgw config sync <file>` reads the YAML file and the secrets that it references, and sends them to the API. The file is the only argument, and the flags can come before or after it. An `_env` reference in the file can name a `PGW_` variable that `.env` holds. A name without the `PGW_` prefix resolves only from the real environment. For the file format, see [Keep a tenant in a file](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md).

| Flag | Default | Description |
| - | - | - |
| `--dry-run` | Off | Prints the plan and changes nothing. It does connect to the database of each new Kamailio upstream, and of each upstream whose Kamailio settings or password change. |
| `--prune` | Off | Deletes the apps, upstreams, and users that the tenant has and the file leaves out, only within the sections that the file names. A file without `apps:` or `upstreams:` leaves that kind alone, and an upstream without `users:` leaves its users alone. An empty list, such as `upstreams: []`, deletes every record of that kind. A deleted app takes its devices with it. A deleted upstream takes its users and devices. |
| `--yes` | Off | Applies a plan that deletes without asking. Use it in scripts. |

pgw always plans first. When the plan is empty, pgw prints `nothing to change`. Otherwise it prints one line for each change, indented by two spaces, then the counts.

| Line | Meaning |
| - | - |
| `+ <kind> <key>` | Creates the record. The kind is `app`, `upstream`, or `user`. |
| `~ <kind> <key>  <fields>` | Updates the record. Lists the fields that change, including a changed secret by its field name. |
| `- <kind> <key>  (<n> devices)` | Deletes the record. A deleted app or upstream shows its number of devices when it has any. |
| `+<a> ~<b> -<c>` | The number of creates, updates, and deletes. |

The key of an app is `<platform>/<bundle_id>`, of an upstream its host, and of a user `<host>/<username>`.

After the plan, pgw applies it and prints `applied`, unless:

* `--dry-run` is set. pgw stops after the plan.
* The plan deletes and `--yes` isn't set. pgw asks `Apply these changes? [y/N] `. Only `y` or `yes` applies the plan. Any other answer prints `pgw: nothing applied` and exits with status 1. Without a terminal, pgw doesn't ask. It prints `pgw: deleting needs confirmation; run in a terminal or pass --yes` and exits with status 1.

Once pgw starts to apply the plan, the server finishes it even if you interrupt the command.

| Error | Meaning |
| - | - |
| `the configuration changed since the preview; run sync again` | The plan that pgw would apply differs from the plan that it showed. pgw applied nothing. |
| `upstream <host>: the host belongs to another tenant` | The file creates an upstream with a host that another tenant uses. pgw applied nothing. |
| `the sync may have been applied, so run sync again, which changes only what still differs` | The connection to the API failed while pgw applied the plan. |

Every other error leaves the tenant unchanged and prints the API's message.

## Next steps

> [card] [Settings](https://docs.pgw.sipmicro.services/reference/settings.md)
>
> Look up the settings and `PGW_*` variables that `pgw serve` reads.

> [card] [Keep a tenant in a file](https://docs.pgw.sipmicro.services/config-as-code/tenant-file.md)
>
> Write the YAML file that `pgw config sync` reads.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.