Admin Commands

Manage API tokens and security settings for your self-hosted Runtime instance.

Admin commands require direct database access. They’re for self-hosting operators, not end users.

Prerequisites

Set these environment variables:

export DATABASE_URL=postgresql://runtm:pass@localhost:5432/runtm
export TOKEN_PEPPER_V1=your-pepper-value

create-token

Create a new API token with specified permissions.

runtm admin create-token \
  --tenant <tenant_id> \
  --principal <principal_id> \
  [options]

Required Arguments

Argument	Description
`--tenant`, `-t`	Tenant/organization ID
`--principal`, `-p`	User/service account ID

Options

Option	Default	Description
`--name`, `-n`	None	Human-readable token name
`--scopes`, `-s`	`read,deploy,delete`	Comma-separated scopes
`--expires`, `-e`	Never	Days until expiration
`--created-by`	`admin-cli`	Creator for audit

Scopes

Scope	Permissions
`read`	List deployments, view logs
`deploy`	Create/update deployments (includes read)
`delete`	Destroy deployments (includes read)
`admin`	Full access, token management

Examples

# Create token with default scopes
runtm admin create-token \
  --tenant org_123 \
  --principal user_456

# Create read-only token
runtm admin create-token \
  --tenant org_123 \
  --principal ci_bot \
  --scopes read \
  --name "CI Read-Only"

# Create token that expires in 30 days
runtm admin create-token \
  --tenant org_123 \
  --principal temp_access \
  --expires 30 \
  --name "Temporary Access"

Output

✓ Token created successfully!

Token: runtm_abc123xyz...

⚠️  IMPORTANT: Save this token now!
   It will NOT be shown again.

ID          a1b2c3d4-...
Tenant      org_123
Principal   user_456
Name        (none)
Scopes      read, deploy, delete
Expires     (never)
Created by  admin-cli

revoke-token

Revoke an API token (soft delete).

runtm admin revoke-token <key_id>

Arguments

Argument	Description
`key_id`	API key UUID to revoke

Options

Option	Default	Description
`--revoked-by`	`admin-cli`	Revoker for audit

Example

runtm admin revoke-token a1b2c3d4-e5f6-7890-abcd-ef1234567890

Output

✓ Token a1b2c3d4-... revoked successfully
  Tenant: org_123
  Principal: user_456
  Name: CI Token
  Revoked by: admin-cli

Revoked tokens immediately stop working. The record is kept for audit purposes.

list-tokens

List API tokens (metadata only, no values).

runtm admin list-tokens [options]

Options

Option	Description
`--tenant`, `-t`	Filter by tenant ID
`--principal`, `-p`	Filter by principal ID
`--include-revoked`	Include revoked tokens

Examples

# List all active tokens
runtm admin list-tokens

# List tokens for a specific tenant
runtm admin list-tokens --tenant org_123

# Include revoked tokens
runtm admin list-tokens --tenant org_123 --include-revoked

Output

API Tokens

ID        TENANT    PRINCIPAL    NAME          SCOPES              STATUS    LAST USED   CREATED
a1b2c3... org_123   user_456     CI Token      read, deploy        active    2024-01-15  2024-01-01
d4e5f6... org_123   admin        Admin Token   admin               active    2024-01-14  2023-12-15
g7h8i9... org_123   old_bot      Old Bot       read                revoked   2023-06-01  2023-05-01

Total: 3 token(s)

rotate-pepper

Guide through pepper rotation process.

runtm admin rotate-pepper \
  --old-pepper <current> \
  --new-pepper <new>

Options

Option	Description
`--old-pepper`	Current pepper (or `TOKEN_PEPPER_V1` env)
`--new-pepper`	New pepper (or `TOKEN_PEPPER_V2` env)
`--dry-run/--execute`	Preview changes (default: dry-run)

Rotation Process

Add new pepper to environment

# In your .env or environment
TOKEN_PEPPER_V1=old-pepper
TOKEN_PEPPER_V2=new-pepper
PEPPER_MIGRATION_VERSIONS=1,2

Deploy with new config

Restart API and worker with updated environment.

Check migration status

runtm admin rotate-pepper --dry-run

Wait for old tokens to expire

Or revoke them manually.

Remove old pepper

# Update .env
CURRENT_PEPPER_VERSION=2
# Remove TOKEN_PEPPER_V1
# Remove PEPPER_MIGRATION_VERSIONS

Example

# Check status
runtm admin rotate-pepper \
  --old-pepper "$TOKEN_PEPPER_V1" \
  --new-pepper "$TOKEN_PEPPER_V2" \
  --dry-run

Output:

Found 5 tokens on pepper v1:
  - a1b2c3d4 (org_123/user_456)
  - e5f6g7h8 (org_123/ci_bot)
  ...

Dry run - no changes made
Run with --execute to update tokens to new pepper

Pepper rotation cannot migrate existing tokens automatically (raw tokens aren’t stored). You must:

Keep old pepper active during migration
Issue new tokens with new pepper
Eventually revoke old tokens

Running in Docker

If running Runtime in Docker, exec into the container:

# Via docker compose
docker compose exec api runtm admin create-token \
  --tenant org_123 \
  --principal admin

# Or start a shell
docker compose exec api bash
runtm admin list-tokens

Security Best Practices

Use specific principals

Create separate tokens for different users/services instead of sharing.

Set expiration dates

Temporary access should expire:

runtm admin create-token --expires 7 ...

Use least privilege

Give only the scopes needed:

CI pipelines: read,deploy
Monitoring: read
Full access: admin (rarely needed)

Audit regularly

Review tokens periodically:

runtm admin list-tokens --include-revoked

Rotate peppers periodically

Even without a breach, rotate peppers annually.

Configuration - Environment variables
Docker Compose - Running services

Open Source

Guides

Features

OSS Templates

CLI Reference

Self-Hosting

OSS API

Deployments

Logs

Domains

User

Admin Commands

Admin Commands

Prerequisites

create-token

Required Arguments

Options

Scopes

Examples

Output

revoke-token

Arguments

Options

Example

Output

list-tokens

Options

Examples

Output

rotate-pepper

Options

Rotation Process

Example

Running in Docker

Security Best Practices

​Admin Commands

​Prerequisites

​create-token

​Required Arguments

​Options

​Scopes

​Examples

​Output

​revoke-token

​Arguments

​Options

​Example

​Output

​list-tokens

​Options

​Examples

​Output

​rotate-pepper

​Options

​Rotation Process

​Example

​Running in Docker

​Security Best Practices

​Related

Admin Commands

Prerequisites

create-token

Required Arguments

Options

Scopes

Examples

Output

revoke-token

Arguments

Options

Example

Output

list-tokens

Options

Examples

Output

rotate-pepper

Options

Rotation Process

Example

Running in Docker

Security Best Practices

Related