CLI

awctl is the command-line client for the Admin API. It manages the same objects the admin console and the Terraform provider manage, inside a tenant, and its command tree mirrors the provider’s resource table, so a resource you know in one is spelled the same way in the other.

Commands follow one shape:

awctl SERVICE RESOURCES VERB [NAME] [FLAGS]

SERVICE is identity or access, RESOURCES is a plural such as realms or clients, and VERB is one of create, list, describe, update, edit, or delete. NAME is a short AWID such as r-01 or a full resource name such as tenants/t-01/realms/r-01; both work.

Install

Binaries are published to the awctl package registry on git.authwise.com for darwin and linux on amd64 and arm64, and for windows on amd64. The project is public, so downloads need no credential. To install a release:

VERSION=AWCTL_VERSION
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
BASE="https://git.authwise.com/api/v4/projects/6/packages/generic/awctl/${VERSION}"

curl -fsSL -o awctl "${BASE}/awctl_${VERSION}_${OS}_${ARCH}"
curl -fsSL -o SHA256SUMS "${BASE}/awctl_${VERSION}_SHA256SUMS"
grep "awctl_${VERSION}_${OS}_${ARCH}" SHA256SUMS | sed "s|awctl_${VERSION}_${OS}_${ARCH}|awctl|" | shasum -a 256 -c -
chmod +x awctl && sudo mv awctl /usr/local/bin/awctl
awctl version

AWCTL_VERSION is a release version such as 0.5.0; the project’s package registry lists them. Releases are plain X.Y.Z versions; a version with a commit suffix is a development build.

Point it at an install

awctl reaches the Admin API over gRPC. Set the endpoint as HOST:PORT in the environment; there is no flag for it:

export AWCTL_ENDPOINT=API_HOST:443

API_HOST is a host from the install’s networking.api.hosts. The connection uses TLS unless AWCTL_INSECURE=true, which is for plaintext development endpoints such as a port-forward to the api Service. See Reach the Admin API for the ways to get there.

Contexts

A context stores the scope identifiers you would otherwise pass on every command. Contexts live in ~/.awctl.yaml, created with mode 0600:

awctl config contexts set prod tenant_id TENANT_ID
awctl config contexts set prod issuer_id ISSUER_ID
awctl config contexts activate prod
awctl identity realms list          # --tenant-id comes from the context

A context can hold tenant_id, issuer_id, realm_id, audience_id, and client_id. An explicit flag always overrides the active context. awctl config contexts list shows them.

Authenticate

There are two ways to authenticate, and awctl picks one deterministically: if any client-credential variable is set, it uses the client-credentials grant and refuses to start if the set is incomplete; otherwise it uses the credential that a browser login stored.

With a machine credential

For scripts, CI, and the first session on a fresh install, use the machine credential the operator minted at install. It is an OAuth 2.0 client_credentials client in the install’s admin tenant; see Read the machine credential.

CREDENTIAL="$(kubectl -n NAMESPACE get secret CR_NAME-admin-credential \
  -o jsonpath='{.data.credential\.json}' | base64 -d)"
export AWCTL_TOKEN_URL="$(jq -r .token_url <<<"$CREDENTIAL")"
export AWCTL_CLIENT_ID="$(jq -r .client_id <<<"$CREDENTIAL")"
export AWCTL_CLIENT_SECRET="$(jq -r .client_secret <<<"$CREDENTIAL")"
export AWCTL_AUDIENCE="$(jq -r .audience <<<"$CREDENTIAL")"
export AWCTL_ENDPOINT=API_HOST:443

awctl identity realms list --tenant-id TENANT_ID

NAMESPACE and CR_NAME are the install’s namespace and the name of its AuthwiseIdentityServer. AWCTL_AUDIENCE is the admin audience’s AWID, an identifier rather than a URL; pass it verbatim. Tokens are minted in process and re-minted before they expire.

As a person

awctl auth login runs the OAuth 2.0 authorization code flow with PKCE in your browser and stores the access token in ~/.awctl.d/credentials/credentials.json with mode 0600:

awctl auth login --issuer https://ADMIN_HOST --client-id CLIENT_ID

ADMIN_HOST is the install’s admin issuer host (spec.bootstrap.admin.issuerHost), and CLIENT_ID is a public client in the admin tenant whose allowed redirect URIs include http://localhost:8990/return. Create one with the Terraform provider or with awctl identity clients create using the machine credential; --return-port changes the port. The flags fall back to AWCTL_AUTH_ISSUER and AWCTL_AUTH_CLIENT_ID.

The stored token is not refreshed. When it expires, commands fail with a hint to run awctl auth login again. awctl auth logout deletes the store.

Output and input

Every verb takes --format table|yaml|json, with --yaml and --json as shorthands, and --fields a,b,c to choose columns. Tables hide sensitive fields; yaml and json do not. list pages through the whole collection automatically.

create and update take flags for the common fields, or --file PATH with a YAML or JSON document of the whole object. edit NAME opens the object in $EDITOR and sends the difference as a field-mask patch.

The command tree

Group	Scope flags	Notes
identity domains	--tenant-id	create ID takes the domain name as its identifier.
identity issuers	--tenant-id	--domain-name, --path, --config, --appearance-profile-id, --labels.
identity realms	--tenant-id
identity audiences, clients, appearance-profiles	--tenant-id --issuer-id	A client takes --audience-id, --display-name, --grant-type, --application-url, --login-url, --post-logout-redirect-uris, --config.
identity client-secrets	--tenant-id --issuer-id --client-id	No create; mint prints the secret once.
identity users, providers, factors	--tenant-id --realm-id	Users also have list-authenticators, revoke-authenticator, list-devices, revoke-device, list-identifiers, remove-identifier.
identity scopes	--tenant-id --issuer-id --audience-id	create ID; add-, remove-, list-access-permissions.
identity themes, assets, certificates, secrets, endpoints	--tenant-id	Certificates: import, rotate, export. Secrets: create, add-version. Endpoints: check, referrers.
identity events	--tenant-id	Read only: list, describe.
access access-permissions, access-roles, access-conditions, access-bindings	--tenant-id --issuer-id --audience-id	Roles: add-, remove-, list-access-permissions.

awctl identity providers import-saml-metadata and export-saml-metadata exchange SAML metadata with an identity provider; awctl identity clients has the same pair for the service-provider side.

Common tasks

Create a realm and list the realms in a tenant:

awctl identity realms create --tenant-id TENANT_ID --display-name Employees
awctl identity realms list --tenant-id TENANT_ID

Mint a client secret and capture it without it reaching your terminal:

awctl identity client-secrets mint \
  --tenant-id TENANT_ID --issuer-id ISSUER_ID --client-id CLIENT_ID \
  --out ./client-secret.txt

--out writes the secret to a file with mode 0600 and refuses to overwrite. The secret is shown once; there is no way to read it again, only to mint a successor.

Read an issuer’s configuration as JSON and inspect one field:

awctl identity issuers describe ISSUER_ID --tenant-id TENANT_ID --json \
  | jq .config

Check an outbound endpoint and see what references it:

awctl identity endpoints check ENDPOINT_ID --tenant-id TENANT_ID
awctl identity endpoints referrers ENDPOINT_ID --tenant-id TENANT_ID

check exits non-zero when the endpoint is unreachable, which suits a readiness script.

List recent events in a tenant:

awctl identity events list --tenant-id TENANT_ID

Working notes

• Secrets go through files or stdin, never flags. identity secrets create reads material from --data-file PATH or from stdin with -. Use printf '%s' rather than echo to avoid sending a trailing newline as part of the secret.
• --config on an issuer replaces the whole config. The server refuses a partial update beneath the realm selector, so read the config, edit it, and write it back whole.
• ALREADY_EXISTS on an access binding means the same audience, subject, role, resource, and condition already have a binding. Expiry is not part of that identity, so extending a grant is an update, not a second create.
• Deletion is refused while referenced. An endpoint, certificate, or issuer that something still references cannot be deleted; endpoints referrers names the holders.
• Revoking a user’s authenticator also revokes their remembered browsers. The revoke and remove verbs prompt unless you pass --yes, and refuse to run without a terminal and without it.
• awctl works inside a tenant. It does not create tenants or grant operator status; those belong to the operator-only tenancy surface.