stella admin — Administrative Operations Reference

Audience: platform administrators and operators managing a Stella Ops deployment.

The stella admin command group provides administrative operations for platform management. These commands require elevated authentication and cover policy management, user administration, feed configuration, diagnostics, and system maintenance.

Overview

This reference documents every stella admin subcommand: its usage, options, examples, required scope, and the backend API it calls. All admin operations are authenticated, scope-gated, and recorded to the audit trail.

Authentication

Admin commands require one of the following authentication methods:

1. OpTok with admin scopes (recommended for production):

   stella auth login
   # Obtain OpTok with admin.* scopes
   stella admin policy export
   

2. Bootstrap API key (for initial setup before Authority configured):

   export STELLAOPS_BOOTSTRAP_KEY="bootstrap-key-from-backend-config"
   stella admin users add admin@example.com --role admin
   

Required Scopes

Command Reference

stella admin policy

Policy management commands for exporting, importing, and validating platform policies.

stella admin policy export

Export the active policy snapshot to a file or stdout.

Usage:

stella admin policy export [--output <path>] [--verbose]

Options:

• -o, --output <path> - Output file path (stdout if omitted)
• -v, --verbose - Enable verbose output

Examples:

# Export to stdout
stella admin policy export

# Export to file
stella admin policy export --output policy-backup.yaml

# Export with timestamp
stella admin policy export --output backup-$(date +%F).yaml

stella admin policy import

Import policy from a YAML or JSON file.

Usage:

stella admin policy import --file <path> [--validate-only] [--verbose]

Options:

• -f, --file <path> - Policy file to import (required)
• --validate-only - Validate without importing
• -v, --verbose - Enable verbose output

Examples:

# Validate policy before importing
stella admin policy import --file new-policy.yaml --validate-only

# Import policy
stella admin policy import --file new-policy.yaml

stella admin policy validate

Validate a policy file without importing.

Usage:

stella admin policy validate --file <path> [--verbose]

Examples:

stella admin policy validate --file policy.yaml

stella admin policy list

List all policy revisions.

Usage:

stella admin policy list [--format <format>] [--verbose]

Options:

• --format <format> - Output format: table (default), json

Examples:

# List as table
stella admin policy list

# List as JSON
stella admin policy list --format json

stella admin users

User management commands for adding, removing, and updating users.

stella admin users list

List platform users.

Usage:

stella admin users list [--role <role>] [--format <format>] [--verbose]

Options:

• --role <role> - Filter by role
• --format <format> - Output format: table (default), json

Examples:

# List all users
stella admin users list

# List all admins
stella admin users list --role admin

# List as JSON
stella admin users list --format json

stella admin users add

Add a new user to the platform.

Usage:

stella admin users add <email> --role <role> [--tenant <id>] [--verbose]

Arguments:

• <email> - User email address

Options:

• -r, --role <role> - User role (required)
• -t, --tenant <id> - Tenant ID (default if omitted)

Available Roles:

• admin - Full platform access
• security-engineer - Security operations
• developer - Development access
• viewer - Read-only access

Examples:

# Add admin user
stella admin users add admin@example.com --role admin

# Add security engineer for specific tenant
stella admin users add alice@example.com --role security-engineer --tenant acme-corp

stella admin users revoke

Revoke user access.

Usage:

stella admin users revoke <email> [--confirm] [--verbose]

Arguments:

• <email> - User email address

Options:

• --confirm - Confirm revocation (required for safety)

Examples:

# Revoke user (requires --confirm)
stella admin users revoke bob@example.com --confirm

Note: The --confirm flag is required to prevent accidental user removal.

stella admin users update

Update user role.

Usage:

stella admin users update <email> --role <role> [--verbose]

Arguments:

• <email> - User email address

Options:

• -r, --role <role> - New user role (required)

Examples:

# Promote user to admin
stella admin users update alice@example.com --role admin

# Change to viewer role
stella admin users update bob@example.com --role viewer

stella admin feeds

Advisory feed management commands.

stella admin feeds list

List configured advisory feeds.

Usage:

stella admin feeds list [--format <format>] [--verbose]

Options:

• --format <format> - Output format: table (default), json

Examples:

# List feeds as table
stella admin feeds list

# List feeds as JSON
stella admin feeds list --format json

stella admin feeds status

Show feed synchronization status.

Usage:

stella admin feeds status [--source <id>] [--verbose]

Options:

• -s, --source <id> - Filter by source ID (all if omitted)

Examples:

# Show status for all feeds
stella admin feeds status

# Show status for specific feed
stella admin feeds status --source nvd

stella admin feeds refresh

Trigger feed refresh.

Usage:

stella admin feeds refresh [--source <id>] [--force] [--verbose]

Options:

• -s, --source <id> - Refresh specific source (all if omitted)
• --force - Force refresh (ignore cache)

Examples:

# Refresh all feeds
stella admin feeds refresh

# Force refresh specific feed
stella admin feeds refresh --source nvd --force

# Refresh OSV feed
stella admin feeds refresh --source osv

stella admin feeds history

Show feed synchronization history.

Usage:

stella admin feeds history --source <id> [--limit <n>] [--verbose]

Options:

• -s, --source <id> - Source ID (required)
• -n, --limit <n> - Limit number of results (default: 10)

Examples:

# Show last 10 syncs for NVD
stella admin feeds history --source nvd

# Show last 50 syncs for OSV
stella admin feeds history --source osv --limit 50

stella admin diagnostics

Readiness and operator diagnostics backed by the Platform service.

stella admin diagnostics health

Show the canonical platform readiness summary, including setup-blocking required dependencies and configured optional post-boot services.

Usage:

stella admin diagnostics health [--detail] [--format <format>]

Options:

• --detail - Include endpoint information in the table output
• --format <format> - Output format: table (default), json

Notes:

• Required dependencies are the same blockers used by stella setup status and setup finalization.
• Optional dependencies are configured post-boot services discovered by the Platform readiness endpoint.
• JSON output is camelCase and intended to stay machine-readable.

Examples:

# Show readiness in the default table view
stella admin diagnostics health

# Include endpoint details for each dependency
stella admin diagnostics health --detail

# Emit the readiness payload for automation
stella admin diagnostics health --format json

stella admin system

System management and health commands.

stella admin system status

Show system health status.

Usage:

stella admin system status [--format <format>] [--verbose]

Options:

• --format <format> - Output format: table (default), json

Examples:

# Show status as table
stella admin system status

# Show status as JSON
stella admin system status --format json

stella admin system info

Show system version, build, and configuration information.

Usage:

stella admin system info [--verbose]

Examples:

stella admin system info

Configuration

Admin commands can be configured via appsettings.admin.yaml:

StellaOps:
  Backend:
    BaseUrl: "https://api.stellaops.example.com"
    Auth:
      OpTok:
        Enabled: true

  Admin:
    DefaultTenant: "default"
    RequireConfirmation: true
    AuditLog:
      Enabled: true
      OutputPath: "~/.stellaops/admin-audit.jsonl"

See etc/appsettings.admin.yaml.example for full configuration options.

Backend API Endpoints

Admin commands call the following backend APIs:

Security Considerations

1. Authentication Required: All admin commands require valid OpTok or bootstrap key
2. Scope Validation: Backend validates admin.* scopes for all operations
3. Audit Logging: All admin operations are logged to audit trail
4. Confirmation for Destructive Ops: Commands like revoke require --confirm flag
5. Bootstrap Mode: Bootstrap key should only be used for initial setup

Troubleshooting

Authentication Errors

HTTP 401: Unauthorized

Solution: Ensure you have a valid OpTok with admin scopes:

stella auth login
stella admin policy export

Missing Scopes

HTTP 403: Forbidden - insufficient scopes

Solution: Request OpTok with required admin.* scopes from platform administrator.

Backend API Not Available

HTTP Error: Connection refused

Solution: Verify backend URL in configuration:

export STELLAOPS_BACKEND__BASEURL="https://api.stellaops.example.com"
stella admin system status

See Also

• CLI reference overview
• Authority service guide
• Air-gap CLI guide