Command Line Interface

The nginx-ui ctl command manages a running Nginx UI instance through its management API. It is intended for infrastructure-as-code, configuration-as-code, deployment automation, and remote administration.

Create an access token

1. Sign in to Nginx UI as an administrator.
2. Open Preferences > Access Tokens.
3. Create a token with the smallest required scope and an expiration date.
4. Copy the token immediately. Nginx UI does not display it again.

The API scopes are:

Scope	Access
api:read	GET, HEAD, and OPTIONS management API requests
api:write	Mutating management API requests and API read access

MCP scopes are independent of API scopes. Granting mcp:write does not grant management API access, and granting api:write does not grant MCP access.

Service tokens cannot access interactive account security operations, reveal protected settings, manage other service tokens, or open the web terminal. Use an authenticated administrator session for those operations.

Configure the client

Set the endpoint and keep the token in a file readable only by the account that runs the automation:

export NGINX_UI_CTL_ENDPOINT=https://nginx-ui.example.com
nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list

The endpoint can also be supplied with --endpoint or NGINX_UI_CTL_ENDPOINT. The token can be supplied through NGINX_UI_CTL_TOKEN, --token-file, or --token-stdin. Prefer a secret file or standard input so the token does not appear in command history or process arguments.

For a private certificate authority, pass its PEM bundle with --ca-file. Use --node-id to route a supported request to a specific cluster node.

Common operations

List and create users:

nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list
nginx-ui ctl --token-file /run/secrets/nginx-ui-token users create \
  --name deploy-user --password-file /run/secrets/deploy-user-password

The predefined-user environment variables remain useful for the initial user in skip-installation deployments. Use ctl users create for users managed after the instance has started.

List certificates and register certificate files that already exist on the Nginx UI server:

nginx-ui ctl --token-file /run/secrets/nginx-ui-token certificates list
nginx-ui ctl --token-file /run/secrets/nginx-ui-token certificates import \
  --name example.com \
  --cert /etc/nginx/ssl/example.com/fullchain.pem \
  --key /etc/nginx/ssl/example.com/privkey.pem

The dedicated certificate commands omit certificate and private-key PEM data from their output so CI logs do not capture key material.

Inspect and control Nginx:

nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx status
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx test
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx reload
nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx restart

Call any management API

The generic api command provides coverage for management operations that do not have a dedicated command:

nginx-ui ctl --token-file /run/secrets/nginx-ui-token api sites?page=1
nginx-ui ctl --token-file /run/secrets/nginx-ui-token api \
  --method POST --data-file site.json sites

Paths are resolved below /api. Query strings are preserved, but absolute URLs are rejected so credentials cannot be redirected to another host. Request and response bodies are limited to 16 MiB.

Token lifecycle

Creating, rotating, and revoking service tokens requires an interactive administrator token, including any required two-factor verification:

nginx-ui ctl --token-file /run/secrets/admin-session-token tokens list
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens create \
  --name ci --scope api:write --expires-at 2027-01-01T00:00:00Z
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens rotate TOKEN_ID
nginx-ui ctl --token-file /run/secrets/admin-session-token tokens revoke TOKEN_ID

Rotation invalidates the previous token immediately. Revocation is permanent.