Skip to main content
The identity commands allow you to manage identities directly from the command line. These commands interact with the Kratos Admin API to perform CRUD operations on identities.

​
Prerequisites

Before using identity commands, ensure:
  • Kratos server is running
  • Admin API endpoint is accessible
  • KRATOS_ADMIN_URL environment variable is set, or use the --endpoint flag
export KRATOS_ADMIN_URL=http://localhost:4434

​
Commands

​
list identities

List all identities in the system. 
kratos list identities [flags]
Alias: kratos ls identities

​
Flags

​
--consistency
string
default:"eventual"
The read consistency level. Can be eventual or strong.
  • eventual - Faster response, may not include recently created/updated identities (replication lag ~5 seconds)
  • strong - Guaranteed to include all identities, but slower
​
--page-token
string
Token for pagination. Use the token from previous response to get the next page.
​
--page-size
integer
default:"250"
Number of items per page.
​
--format
string
default:"table"
Output format: json, yaml, json-pretty, or table.
​
--endpoint
string
Admin API endpoint URL. Can also be set via KRATOS_ADMIN_URL environment variable.

​
Examples

kratos list identities

​
Output example

[
  {
    "id": "d96e86d9-4c1d-4f1c-8b79-1b2c9fcda9e3",
    "schema_id": "default",
    "schema_url": "http://localhost:4433/schemas/ZGVmYXVsdA",
    "state": "active",
    "state_changed_at": "2024-01-15T10:30:00Z",
    "traits": {
      "email": "user@example.com",
      "name": "John Doe"
    },
    "verifiable_addresses": [
      {
        "id": "f9c2e3a1-5b7d-4c8e-9f1a-2b3c4d5e6f7a",
        "value": "user@example.com",
        "verified": true,
        "via": "email",
        "status": "completed"
      }
    ],
    "recovery_addresses": [
      {
        "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "value": "user@example.com",
        "via": "email"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

​
get identity

Get one or more identities by their ID(s). 
kratos get identity <id-1> [id-2] [id-n] [flags]

​
Flags

​
--include-credentials
string[]
Include third-party credentials in the response. Currently only oidc is supported.Short flag: -i
​
--format
string
default:"table"
Output format: json, yaml, json-pretty, or table.
​
--endpoint
string
Admin API endpoint URL.

​
Examples

kratos get identity d96e86d9-4c1d-4f1c-8b79-1b2c9fcda9e3
To query identities by attributes like email address, use the list command with jq to filter results, then pass the IDs to get identity.

​
delete identity

Delete one or more identities by their ID(s). 
kratos delete identity <id-0> [id-1] [id-n] [flags]
This operation is irreversible. Deleted identities cannot be recovered.

​
Flags

​
--format
string
default:"table"
Output format: json, yaml, json-pretty, or table.
​
--endpoint
string
Admin API endpoint URL.

​
Examples

kratos delete identity d96e86d9-4c1d-4f1c-8b79-1b2c9fcda9e3

​
import identities

Import one or more identities from JSON files or STDIN. 
kratos import identities [file-1.json] [file-2.json] [file-n.json] [flags]

​
Description

Import identities into Kratos from JSON files or standard input. Files can contain a single identity or an array of identities.
Use validate identity to test the validity of identity files before importing.

​
Flags

​
--format
string
default:"table"
Output format for the imported identities.
​
--endpoint
string
Admin API endpoint URL.

​
Examples

cat > identity.json <<EOF
{
  "schema_id": "default",
  "traits": {
    "email": "user@example.com",
    "name": "Jane Doe"
  }
}
EOF

kratos import identities identity.json

​
Identity file format

The import command expects JSON files with the following structure: 
{
  "schema_id": "default",
  "state": "active",
  "traits": {
    "email": "user@example.com",
    "name": "User Name"
  },
  "verifiable_addresses": [
    {
      "value": "user@example.com",
      "verified": true,
      "via": "email"
    }
  ],
  "credentials": {
    "password": {
      "config": {
        "hashed_password": "$argon2id$..."
      }
    }
  }
}

​
validate identity

Validate local identity files against the identity schema and API payload definition. 
kratos validate identity [file.json] [file-2.json] [file-n.json] [flags]

​
Description

This command validates identity files before importing them. It checks:
  1. The JSON structure against the API schema
  2. The identity traits against the configured identity schema
Identities can be supplied via STDIN or JSON files (single identity or array).

​
Flags

​
--endpoint
string
Admin API endpoint URL (required to fetch identity schemas).
​
--format
string
Output format.

​
Examples

kratos validate identity identity.json

​
Success output

All identity files are valid.

​
Error output

If validation fails, you’ll see detailed error messages: 
identity.json: not valid

traits.email:
  - Format must be "email"

schema_id:
  - Expected key "schema_id" to be defined in identity file

​
Advanced usage

​
Filtering with jq

The list identities command combined with jq provides powerful filtering capabilities: 
kratos list identities --format json | \
  jq 'map(select(.traits.email | endswith("@example.com")))'

​
Bulk operations

kratos delete identity $(
  kratos list identities --format json | \
  jq -r 'map(select(.verifiable_addresses[].verified == false)) | .[].id'
)

​
Error handling

All identity commands return appropriate exit codes:
  • 0 - Success
  • 1 - Failure (with error message)
Failed operations are reported with detailed error messages: 
kratos get identity invalid-id
# Output:
# invalid-id: Not Found
# exit code: 1
When operating on multiple identities, partial failures are reported: 
kratos delete identity valid-id invalid-id
# Output:
# ID                                  
# valid-id
# 
# ERRORS:
# invalid-id: Not Found
# exit code: 1

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us