git.stella-ops.org/docs/cli/admin-reference.md

stella admin - Administrative Operations Reference

Sprint: SPRINT_4100_0006_0005 - Admin Utility Integration

Overview

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

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 Group	Required Scope	Purpose
stella admin policy	admin.policy	Policy management operations
stella admin users	admin.users	User administration
stella admin feeds	admin.feeds	Feed management
stella admin system	admin.platform	System operations

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 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:

Endpoint	Method	Command
/api/v1/admin/policy/export	GET	stella admin policy export
/api/v1/admin/policy/import	POST	stella admin policy import
/api/v1/admin/policy/validate	POST	stella admin policy validate
/api/v1/admin/policy/revisions	GET	stella admin policy list
/api/v1/admin/users	GET	stella admin users list
/api/v1/admin/users	POST	stella admin users add
/api/v1/admin/users/{email}	DELETE	stella admin users revoke
/api/v1/admin/users/{email}	PATCH	stella admin users update
/api/v1/admin/feeds	GET	stella admin feeds list
/api/v1/admin/feeds/status	GET	stella admin feeds status
/api/v1/admin/feeds/{id}/refresh	POST	stella admin feeds refresh
/api/v1/admin/feeds/{id}/history	GET	stella admin feeds history
/api/v1/admin/system/status	GET	stella admin system status
/api/v1/admin/system/info	GET	stella admin system info

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
• Authority Documentation
• Operational Procedures