nauthera-cli Reference

Docs version v1 (main) · Nauthera is pre-1.0, in a design-partner program · Updated November 4, 2026

nauthera-cli drives the gRPC AdminService from a terminal. For clients and identity providers, it uses the same idempotent upserts the operator drives. It is a local development tool; in a cluster the operator manages clients. It connects in one of two ways:

• Without TLS, the default. Only a server with server.grpc.allow_insecure: true answers, and the server accepts that setting only on a loopback server.grpc.address, as in config.dev.yaml and the chart's kind profiles.
• With mutual TLS, when you pass --tls-ca-file, --tls-cert-file and --tls-key-file together. The Compose stack runs the control plane this way: just certs writes a CA, the server's key pair and a nauthera-cli client certificate to .certs/grpc/, and the server admits only that client certificate.

Run it from a checkout of nauthera-server:

go run ./cmd/nauthera-cli <command> [flags]

Against the Compose stack:

go run ./cmd/nauthera-cli get org \
  --tls-ca-file .certs/grpc/ca.pem \
  --tls-cert-file .certs/grpc/client.pem \
  --tls-key-file .certs/grpc/client-key.pem

To reach a server in a kind cluster, where the AdminService listens on 127.0.0.1 inside the pod, port-forward the deployment first:

kubectl -n nauthera port-forward deploy/nauthera-nauthera-server 9091:9091

#Global flags

Each setting can also come from an environment variable, NAUTHERA_CLI_ followed by the upper-cased flag name with dashes as underscores, for example NAUTHERA_CLI_ADDR or NAUTHERA_CLI_TLS_CA_FILE. The three TLS settings go together: setting only some of them is an error. A flag on the command line wins, then the environment, then the config file.

#Organizations

#create org <slug>

Creates an organization. It refuses a slug that already exists. It returns no secret for the organization's {slug}-admin-m2m client, so nobody holds that secret and the client cannot be used. An organization created through the admin API gets that secret once, as admin_m2m_secret.

FIPS mode can be set only when the organization is created. FAPI mode, email verification, the second-factor policy and the zones can be changed later with update org. An organization's policy can only tighten the deployment's; see Configuration. See also Organizations.

# policy.yaml
methods: [passkey, totp]
required: true
rules:
  - name: passkey-off-site
    outside_zones: [office]
    methods: [passkey]

spare_zones names zones of the deployment's security.network_zones only, because no level spares a sign-in the deployment would not.

go run ./cmd/nauthera-cli create org acme --display-name "Acme" \
  --zone office=203.0.113.0/24 --second-factor-file policy.yaml

#update org <slug>

Changes an existing organization. Only the flags given are changed; pass --fapi-mode=false or --require-email-verification=false to lift one. It refuses a call that changes nothing, and answers an unknown slug with an error.

The slug and FIPS mode are fixed at creation. The main organization's settings come from orgs.main in the server's configuration, not from here; the control plane never changes the main organization.

#get org [slug]

Reads one organization, or lists all of them when the slug is omitted.

#delete org <slug>

Deletes an organization's record. Its users, clients and sessions stay in the database, and its reserved admin clients keep the slug taken, so create org with the same slug then fails with an internal error (#283). Deleting an organization that does not exist succeeds. The main organization cannot be deleted. See Deleting an org.

#Clients

#create client <client-id>

Creates the client, or replaces its configuration if it exists. A secret is generated and printed once, by the run that mints it: the run that creates the client, or a later run that switches a client without a secret, such as a public one, to client_secret_basic. Store it then. Running the command again never rotates the secret: to get a new one, delete the client and create it again.

Without --public or --jwks-uri, the client authenticates with client_secret_basic.

go run ./cmd/nauthera-cli create client my-app \
  --org acme \
  --redirect-uri https://app.example.com/callback \
  --post-logout-redirect-uri https://app.example.com/

#get client [name]

Reads one client by resource name, or lists the clients in --namespace when the name is omitted. Add -A (--all-namespaces) to list every namespace.

#delete client <name>

Deletes a client by resource name. Deleting one that does not exist succeeds.

#Identity providers

#create identity-provider <slug>

Creates or replaces an external OpenID Connect provider, or GitHub (--provider-issuer https://github.com/login/oauth), that an organization's users can sign in with (see Social sign-in). Like create client, it is an idempotent upsert, stored under --namespace and the resource name. It prints the redirect URI to register at the provider. A client offers the provider with create client --identity-provider <slug>.

printf '%s' "$GOOGLE_CLIENT_SECRET" | go run ./cmd/nauthera-cli create identity-provider google \
  --org acme --display-name Google \
  --provider-issuer https://accounts.google.com \
  --client-id 1234.apps.googleusercontent.com \
  --client-secret-file /dev/stdin --trust-email

There is no get or delete command for identity providers yet; use the admin API, the dashboard or an IdentityProvider resource.

#What it cannot do

There are no commands for branding, users, roles or client labels, and no get or delete for identity providers. Write branding with the gRPC UpsertBranding call directly or a Branding resource. Users and their roles are managed through the admin API and the admin dashboard.