User Commands

The stategraph user command group provides user identity, access token, and tenant membership operations.

Commands

Command Description
stategraph user whoami Display current user information
stategraph user tenants list List tenants you belong to
stategraph user access-tokens create Create a capability-scoped access token
stategraph user access-tokens list List your access tokens
stategraph user access-tokens delete Delete (revoke) an access token

stategraph user whoami

Display information about the currently authenticated user. stategraph whoami is a top-level alias for the same command.

stategraph user whoami

Example

stategraph user whoami

By default, output is a field | value table:

field                 value
--------------------  ------------------------------------
id                    550e8400-e29b-41d4-a716-446655440000
name                  Jane Smith
email                 jane@example.com
type                  User
avatar_url
auth_origin           local
capabilities
  admin                 no
  access-token-create   no
  access-token-refresh  no
  preview               yes
    tenants             all
    states              all
  commit                yes
    tenants             all
    states              all
  sudo                  no
  users-manage          no

For scripting, use --format json:

stategraph user whoami --format json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "type": "user",
  "capabilities": {
    "preview": {},
    "commit": {}
  }
}

The response includes a capabilities object describing what the identity is allowed to do (admin, commit, preview, sudo, users-manage, access-token-create, access-token-refresh). Admin and role status are expressed through capabilities.admin rather than a boolean is_admin flag. See Access Tokens & Capabilities for the full model.

This command is useful for:
- Verifying your authentication is working
- Checking which account you're logged in as
- Getting your user ID for API calls

stategraph user tenants list

List all tenants that the current user is a member of.

stategraph user tenants list

Example

stategraph user tenants list

By default, output is an id | name table:

id                                    name
------------------------------------  -----------
550e8400-e29b-41d4-a716-446655440000  production
660e8400-e29b-41d4-a716-446655440001  staging
770e8400-e29b-41d4-a716-446655440002  development

For scripting, use --format simple (tab-separated, no header) or --format json:

stategraph user tenants list --format simple

550e8400-e29b-41d4-a716-446655440000    production
660e8400-e29b-41d4-a716-446655440001    staging
770e8400-e29b-41d4-a716-446655440002    development

stategraph user access-tokens

Create, list, and revoke capability-scoped access tokens for the current user. Each token authenticates the CLI, Terraform, and API as a Bearer token and is bounded by a set of capabilities. See Access Tokens & Capabilities for the full capability model.

stategraph user access-tokens create

Create an access token. --name is required; the capability flags scope what the token may do. With no capability flags, the token inherits the creating session's capabilities.

stategraph user access-tokens create --name ci-prod-apply --commit --commit-state 'sid=*'
Flag Description
--name <name> Name for the token (required).
--admin Grant admin (full access).
--commit Grant commit; restrict with --commit-tenant <uuid> / --commit-state <STATE_ID=PATTERN>.
--preview Grant preview; restrict with --preview-tenant <uuid> / --preview-state <STATE_ID=PATTERN>.
--users-manage Grant users-manage; restrict with --users-manage-tenant <uuid>.
--sudo-user <uuid> Grant sudo over a user (repeatable).
--access-token-create Grant the access-token-create capability.
--access-token-refresh Grant the access-token-refresh capability.
--capabilities-json <json> Raw capabilities JSON. Mutually exclusive with the individual flags above.

The token value is printed once in the response and cannot be retrieved again:

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

stategraph user access-tokens list

List the current user's tokens.

stategraph user access-tokens list

The default table shows id, name, created_at, expiration, owner_name, and owner_type. Use --format json for the full objects (which also include owner_id).

stategraph user access-tokens delete

Delete (revoke) a token by id. The --token-id flag is required.

stategraph user access-tokens delete --token-id f02791c8-aa63-4cdf-acae-a7c968d8a831

Scripting Examples

Get tenant ID by name

TENANT_ID=$(stategraph user tenants list --format simple | grep "production" | awk '{print $1}')
echo "Production tenant: $TENANT_ID"

Verify authentication in CI

#!/bin/bash
if ! stategraph user whoami > /dev/null 2>&1; then
  echo "Authentication failed. Check STATEGRAPH_API_KEY."
  exit 1
fi
echo "Authenticated successfully"

List all states across all tenants

stategraph user tenants list --format simple | while read id name; do
  echo "=== $name ==="
  stategraph states list --tenant "$id" --format json | jq -r '.results[].name'
done

Next Steps