CLI reference

CLI commands are non-interactive. Write commands execute immediately, except when a supported --dry-run flag is set. Place flags after the subcommand. Use kticket <command> --help or kticket access <command> --help for command-specific options.

Long options use two dashes, for example --username alice or --username=alice. Help and examples use this style consistently; existing single-dash long options remain accepted for compatibility.

The --kubeconfig and --lang flags may also precede the command. A command-specific --kubeconfig overrides the root value. The --lang value only affects the TUI and is ignored by CLI commands.

Commands

Batch issuance and namespace multi-selection are available in the TUI. CLI issue accepts one account and one grant selection per invocation.

License commands

kticket license machine-id
kticket license install /path/to/kticket-license.ktlicense
kticket license status
kticket license inspect /path/to/kticket-license.ktlicense

See license purchase and activation for purchasing, installation paths, --force, and KTICKET_LICENSE_FILE.

Cluster and account selection

CLI account commands accept --kubeconfig and --context. The kubeconfig defaults to KUBECONFIG, then ~/.kube/config; the context defaults to that configuration’s current context. Context names must already exist in the kubeconfig.

--namespace selects the account namespace, where the ServiceAccount lives. It defaults to kticket-users for issue, revoke, and access commands. For list, an omitted namespace means all namespaces.

The account namespace is independent of the target namespace where access is granted. Use --role-namespace with issue and --target-namespace with access commands for the target.

Issue credentials

Grant the existing edit ClusterRole within app-prod:

kticket issue --username bob --duration 8h \
  --access namespace --role edit --role-namespace app-prod \
  --output ./bob.kubeconfig

Bind an existing namespaced Role:

kticket issue --username carol --access role \
  --role support --role-namespace app-prod

Issue a credential without adding grants:

kticket issue --username alice --access none \
  --duration 1h --output ./alice-laptop.kubeconfig

--access none preserves existing permissions. Reissuing for an existing account creates another token for the same ServiceAccount; it does not replace earlier tokens.

For recipients who use a different API endpoint:

kticket issue --username eve --access namespace \
  --role view --role-namespace app-prod \
  --server https://api.example.com:6443

The account namespace and ServiceAccount are created when missing. Roles and target namespaces must already exist. The one exception is binding an existing ClusterRole within the account namespace created by that issuance.

Issue options

Omitting access flags grants cluster-wide cluster-admin access. Use explicit flags when a narrower scope is required. issue has no --dry-run option.

Generated kubeconfig

The file includes the bearer token, API endpoint, and configured CA data, including CA data read from a file referenced by the administrator’s kubeconfig. Without a configured CA, the client uses system trust roots. In insecure mode, the output omits CA data.

The cluster name comes from the selected administrator context. The generated context is <account>@<cluster>, with that context selected as current-context. Its default namespace is the account namespace; use kubectl --namespace for workloads elsewhere. --server changes the endpoint without changing the cluster name. If no cluster name is available, kticket uses cluster.

The default filename includes the account and cluster names, such as alice.production-eu.kubeconfig. CLI --output selects a file; the TUI requires an existing directory.

Each issued credential has a distinct kubeconfig user alias. See credential records to find issuance and expiry times.

List accounts and credentials

kticket list
kticket list --context my-cluster --namespace kticket-users
kticket list --credentials

The account list includes managed role bindings. --credentials adds recorded credential IDs, timestamps, and audit IDs. Records describe credentials issued and recorded by kticket; they are not a complete inventory of usable tokens.

Revoke an account

kticket revoke --context my-cluster --namespace kticket-users --username alice

Revocation deletes the managed ServiceAccount first, then cleans up its managed bindings. It affects every token for that account UID. It does not delete the namespace or local kubeconfig files. The username must identify an existing managed account.

See revocation and failure handling before recreating an account whose binding cleanup failed.

Manage grants

All access commands require --username and accept the cluster and account selection flags above. --expected-uid optionally requires a particular ServiceAccount UID, allowing scripts to reject an account that has been deleted and recreated.

Add a grant to an existing account, first previewing the change:

kticket access grant --username alice \
  --target-namespace app-staging --cluster-role edit --dry-run
kticket access grant --username alice \
  --target-namespace app-staging --cluster-role edit

Use --role support for a namespaced Role. Choose exactly one of --cluster-role and --role. The default scope is namespace; cluster-wide grants require --scope cluster --cluster-role NAME and no target namespace.

List grants, then replace or remove one using its grant ID:

kticket access list --username alice

# Replace GRANT_ID with an ID from the list.
kticket access replace --username alice --grant-id GRANT_ID \
  --target-namespace app-staging --cluster-role view

# List again, then use the current grant ID for removal.
kticket access list --username alice
kticket access remove --username alice --grant-id CURRENT_GRANT_ID

grant, replace, and remove support --dry-run, which computes a plan without writing resources. Without it, changes apply immediately. Removing a grant preserves the account and its credentials. External assignments remain outside kticket’s control.

All referenced roles and target namespaces must exist. Access commands never create namespaces. Several grants may coexist in one namespace. Changes apply to all valid credentials for the account without extending their expiry.

Declare a grant set

Create alice-access.yaml:

grants:
  - scope: namespace
    namespace: app-prod
    roleKind: ClusterRole
    roleName: view
  - scope: namespace
    namespace: app-staging
    roleKind: ClusterRole
    roleName: edit

Preview and apply it:

kticket access plan --username alice --file alice-access.yaml
kticket access apply --username alice --file alice-access.yaml

The file describes the complete desired set of kticket-managed grants for that account. Omitted managed grants are removed; external assignments are preserved. grants: [] removes all managed grants. The grants field must be an explicit array; null, duplicate grants, and unknown fields are rejected.

Use roleKind: Role for a namespaced Role. For a cluster-wide grant, use scope: cluster and roleKind: ClusterRole, and omit namespace.

apply computes a fresh plan from the file and current cluster state. It does not execute a previously saved plan. Replacements remove obsolete bindings before creating new ones, which can briefly interrupt access. See permission changes for partial-failure behavior.

Check an operation

Check whether an account can read pod logs:

kticket access check --username alice \
  --target-namespace app-staging --resource pods/log --verb get

The check uses SubjectAccessReview with the account’s Kubernetes identity and groups. A named resource need not exist: this is an authorization query, not a resource request. Results are ALLOWED, DENIED, or UNAVAILABLE; the CLI exits unsuccessfully unless the result is ALLOWED.

The grant list shows known RBAC assignments, not every effective permission. An external assignment may still allow an operation after a managed grant is removed.