Documentation

Identity Management Commands

Commands for managing users, agent identities, API keys, and OAuth consents.

All commands require a running server and admin credentials:

bash
export SHARK_ADMIN_TOKEN=$(cat admin.key.firstboot)
export SHARK_URL=http://localhost:8080

User Commands (shark user)

shark user list

List all users.

Synopsis

bash
shark user list [flags]

Flags

FlagTypeDefaultDescription
--limitint50Maximum number of users to return
--searchstring(none)Filter by email or name (substring match)
--jsonboolfalseEmit JSON array

Examples

bash
# List first 50 users
shark user list

# Search by email prefix
shark user list --search alice

# All users as JSON, pipe to jq
shark user list --json | jq '.[].email'

# Increase limit
shark user list --limit 200

shark user create

Create a new user.

Synopsis

bash
shark user create --email <email> [flags]

Flags

FlagTypeDefaultDescription
--emailstring(required)User email address
--namestring(none)Display name
--passwordstring(none)Initial password (optional; user can set via magic link otherwise)
--jsonboolfalseEmit created user as JSON

Examples

bash
# Minimal creation
shark user create --email alice@example.com

# With display name and password
shark user create --email bob@example.com --name "Bob Smith" --password s3cr3t

# Capture new user ID
ID=$(shark user create --email dev@example.com --json | jq -r '.data.id')

shark user show

Show a single user by ID.

Synopsis

bash
shark user show <id> [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit user object as JSON

Examples

bash
shark user show usr_abc123

shark user show usr_abc123 --json | jq .data

shark user update

Update a user's fields (partial update — only changed flags are sent).

Synopsis

bash
shark user update <id> [flags]

Flags

FlagTypeDefaultDescription
--namestring(none)New display name
--emailstring(none)New email address
--email-verifiedboolfalseSet email-verified state
--jsonboolfalseEmit updated user as JSON

Examples

bash
# Rename user
shark user update usr_abc123 --name "Alice A."

# Mark email as verified
shark user update usr_abc123 --email-verified

# Change email
shark user update usr_abc123 --email newalice@example.com --json

Gotchas

  • At least one flag must be provided; the command errors if nothing changes.

shark user delete

Delete a user (destructive — irreversible).

Synopsis

bash
shark user delete <id> [flags]

Flags

FlagTypeDefaultDescription
--yesboolfalseSkip interactive confirmation prompt
--jsonboolfalseEmit {"deleted":"<id>"}

Examples

bash
# Interactive prompt
shark user delete usr_abc123

# Skip prompt (scripts / CI)
shark user delete usr_abc123 --yes

shark user delete usr_abc123 --yes --json

Agent Commands (shark agent)

Agents are non-human identities (services, bots, workers) that authenticate via OAuth client credentials or DPoP-bound tokens.

shark agent register

Register a new agent identity. The client secret is shown only once.

Synopsis

bash
shark agent register --name <name> [flags]

Flags

FlagTypeDefaultDescription
--namestring(required)Human-readable agent name
--descriptionstring(none)Optional description
--appstring(none)App slug to associate this agent with (stored in metadata)
--jsonboolfalseEmit created agent as JSON

Examples

bash
# Register an agent
shark agent register --name "email-service"

# With description and app association
shark agent register --name "followup-service" \
  --description "Sends follow-up emails" \
  --app my-saas

# Capture credentials
CREDS=$(shark agent register --name "worker" --json)
CLIENT_ID=$(echo $CREDS | jq -r '.data.client_id')
SECRET=$(echo $CREDS | jq -r '.data.client_secret')

Gotchas

  • The client_secret is shown exactly once. Save it immediately — there is no way to retrieve it again.
  • To get a new secret, use shark agent rotate-secret <id>.

shark agent show

Show a single agent by ID.

Synopsis

bash
shark agent show <id> [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit agent object as JSON

Examples

bash
shark agent show agt_abc123

shark agent show agt_abc123 --json | jq .data.client_id

shark agent update

Update an agent's name or description.

Synopsis

bash
shark agent update <id> [flags]

Flags

FlagTypeDefaultDescription
--namestring(none)New agent name
--descriptionstring(none)New description
--jsonboolfalseEmit updated agent as JSON

Examples

bash
shark agent update agt_abc123 --name "email-service-v2"

shark agent update agt_abc123 --description "Handles transactional email" --json

shark agent delete

Deactivate (soft-delete) an agent.

Synopsis

bash
shark agent delete <id> [flags]

Flags

FlagTypeDefaultDescription
--yesboolfalseSkip confirmation prompt
--jsonboolfalseEmit {"deleted":"<id>"}

Examples

bash
shark agent delete agt_abc123

shark agent delete agt_abc123 --yes

shark agent rotate-secret

Rotate an agent's client secret. The new secret is shown only once.

Synopsis

bash
shark agent rotate-secret <id> [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit {"client_secret":"..."} as JSON

Examples

bash
shark agent rotate-secret agt_abc123

# Capture new secret
NEW_SECRET=$(shark agent rotate-secret agt_abc123 --json | jq -r '.data.client_secret')

shark agent revoke-tokens

Revoke all active OAuth tokens for an agent (force re-authentication).

Synopsis

bash
shark agent revoke-tokens <id> [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit {"revoked":<count>}

Examples

bash
shark agent revoke-tokens agt_abc123

shark agent revoke-tokens agt_abc123 --json

API Key Commands (shark api-key)

Admin API keys authenticate CLI and programmatic access to the admin API.

shark api-key create

Create a new admin API key. The key value is shown only once.

Synopsis

bash
shark api-key create --name <name> [flags]

Flags

FlagTypeDefaultDescription
--namestring(required)Name for the API key
--jsonboolfalseEmit created key as JSON

Examples

bash
shark api-key create --name "ci-deploy"

# Capture key value
KEY=$(shark api-key create --name "staging" --json | jq -r '.data.key')

Gotchas

  • The key value is shown exactly once at creation. Set it as SHARK_ADMIN_TOKEN before it scrolls off.

shark api-key list

List all API keys (key values are never shown — prefix only).

Synopsis

bash
shark api-key list [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit JSON array

Examples

bash
shark api-key list

shark api-key list --json | jq '.[].name'

shark api-key revoke

Permanently revoke an API key by ID.

Synopsis

bash
shark api-key revoke <id> [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit {"revoked":"<id>"}

Examples

bash
shark api-key revoke key_abc123

shark api-key revoke key_abc123 --json

shark api-key rotate

Rotate an API key — generates a new value, invalidates the old one. New key shown once.

Synopsis

bash
shark api-key rotate <id> [flags]

Flags

FlagTypeDefaultDescription
--jsonboolfalseEmit {"key":"..."} with new value

Examples

bash
shark api-key rotate key_abc123

NEW_KEY=$(shark api-key rotate key_abc123 --json | jq -r '.data.key')

shark consents list

List OAuth consents granted by users.

Synopsis

bash
shark consents list [flags]

Flags

FlagTypeDefaultDescription
--user / -ustring(none)Filter by user ID
--jsonboolfalseEmit JSON array

Examples

bash
# List all consents
shark consents list

# Filter to one user
shark consents list --user usr_abc123

shark consents list --json | jq '.[].scopes'
Previous01-serverNext03-applications