auth token

Personal Access Token management commands. PATs allow ndcli to authenticate using the NDCLI_TOKEN environment variable instead of the interactive browser-based login — useful for CI/CD pipelines and headless servers.

See the Personal Access Tokens guide for a conceptual overview and security best practices.

Commands

Command	Description
auth token create	Create a new personal access token
auth token list	List your personal access tokens
auth token revoke	Revoke a personal access token

---

auth token create

Create a new personal access token. The full token value is displayed once at creation and cannot be retrieved afterwards.

ndcli auth token create --name <name> --scope <RW|RO> [--org <org>] [--expiry <duration>]

Flags

Flag	Type	Required	Default	Description
--name	string	Yes	—	Human-readable label for the token. Unique within your account for good: the name of a revoked or expired token can’t be used again (ALREADY_EXISTS).
--scope	string	Yes	—	RW (read and write) or RO (read only).
--org	string	No	—	Restrict the token to a single organization slug. Omit to allow access to all orgs.
--expiry	string	No	90d	Token lifetime. One of: 30d, 60d, 90d, 180d, 365d, never.

An account can have 25 active tokens; revoked and expired tokens don’t count. Past that, create is refused with TOKEN_LIMIT_REACHED until you revoke one.

Examples

# Create a read-write token valid for 90 days
ndcli auth token create --name "github-ci" --scope rw --expiry 90d

✓ Personal access token created

  ⚠  Copy your token now — it will NOT be shown again.

  Token:  ndpat_Jj8IYRumwQ9GV4nfqrymvLBbUUnY8LAkuEecJnIrk1U

  Name:   github-ci
  Scope:  RW
  Expires: 2026-08-24

  Set NDCLI_TOKEN=<token> to use static auth without interactive login.

# Create a read-only token scoped to one org, never expiring
ndcli auth token create --name "readonly-monitor" --scope ro --org ops --expiry never

Notes

Caution

This command requires interactive authentication (ndcli auth login). It cannot be run when NDCLI_TOKEN is set in the environment. To create a token in a CI context, run this command locally first.

---

auth token list

List your personal access tokens. With an interactive login, or a token created without --org, it lists every token for your account. With a token restricted to one organization, it lists only the tokens restricted to that same organization. Shows metadata only — the full token value is never displayed after creation.

ndcli auth token list

Flags

None. Supports the global -f output format flag (table, json, simple, detailed).

Examples

ndcli auth token list

╭──────────────────┬──────────────┬───────┬─────┬────────────┬───────────┬─────────╮
│ NAME             │ PREFIX       │ SCOPE │ ORG │ EXPIRES    │ LAST USED │ STATUS  │
├──────────────────┼──────────────┼───────┼─────┼────────────┼───────────┼─────────┤
│ github-ci        │ ndpat_Jj8IYR │ RW    │ -   │ 2026-08-24 │ 2m        │ active  │
│ readonly-monitor │ ndpat_aB3xYz │ RO    │ ops │ Never      │ Never     │ active  │
╰──────────────────┴──────────────┴───────┴─────┴────────────┴───────────┴─────────╯

Total: 2 token(s)

Output fields

Field	Description
NAME	The label assigned at creation.
PREFIX	The first characters of the token (for identification without exposing the secret).
SCOPE	RW or RO.
ORG	Organization the token is scoped to, or - for all orgs.
EXPIRES	Expiration date, or Never.
LAST USED	Time since last authenticated request, or Never if unused.
STATUS	active or expired.

This command works with both interactive (ndcli auth login) and PAT (NDCLI_TOKEN) authentication. A token restricted to one organization lists only the tokens restricted to that same organization.

---

auth token revoke

Permanently revoke a personal access token by name. Any in-flight requests using the revoked token will immediately receive an authentication error.

ndcli auth token revoke <name> [--yes]

Arguments

Argument	Description
<name>	Name of the token to revoke (as shown in auth token list).

Flags

Flag	Type	Default	Description
--yes	bool	false	Skip the confirmation prompt. Useful for scripting.

Examples

# Revoke with confirmation prompt
ndcli auth token revoke github-ci

# Revoke without confirmation (for scripts)
ndcli auth token revoke github-ci --yes

Danger

Revoking a token is permanent and cannot be undone. Any pipeline or script using the token will fail immediately after revocation. Create a replacement token before revoking if you need uninterrupted access.

Caution

This command requires interactive authentication (ndcli auth login). It cannot be run when NDCLI_TOKEN is set in the environment.