# 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):
   ```bash
   stella auth login
   # Obtain OpTok with admin.* scopes
   stella admin policy export
   ```

2. **Bootstrap API key** (for initial setup before Authority configured):
   ```bash
   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:**
```bash
stella admin policy export [--output <path>] [--verbose]
```

**Options:**
- `-o, --output <path>` - Output file path (stdout if omitted)
- `-v, --verbose` - Enable verbose output

**Examples:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
stella admin policy validate --file <path> [--verbose]
```

**Examples:**
```bash
stella admin policy validate --file policy.yaml
```

#### stella admin policy list

List all policy revisions.

**Usage:**
```bash
stella admin policy list [--format <format>] [--verbose]
```

**Options:**
- `--format <format>` - Output format: `table` (default), `json`

**Examples:**
```bash
# 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:**
```bash
stella admin users list [--role <role>] [--format <format>] [--verbose]
```

**Options:**
- `--role <role>` - Filter by role
- `--format <format>` - Output format: `table` (default), `json`

**Examples:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
stella admin users revoke <email> [--confirm] [--verbose]
```

**Arguments:**
- `<email>` - User email address

**Options:**
- `--confirm` - Confirm revocation (required for safety)

**Examples:**
```bash
# 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:**
```bash
stella admin users update <email> --role <role> [--verbose]
```

**Arguments:**
- `<email>` - User email address

**Options:**
- `-r, --role <role>` - New user role (required)

**Examples:**
```bash
# 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:**
```bash
stella admin feeds list [--format <format>] [--verbose]
```

**Options:**
- `--format <format>` - Output format: `table` (default), `json`

**Examples:**
```bash
# 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:**
```bash
stella admin feeds status [--source <id>] [--verbose]
```

**Options:**
- `-s, --source <id>` - Filter by source ID (all if omitted)

**Examples:**
```bash
# 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:**
```bash
stella admin feeds refresh [--source <id>] [--force] [--verbose]
```

**Options:**
- `-s, --source <id>` - Refresh specific source (all if omitted)
- `--force` - Force refresh (ignore cache)

**Examples:**
```bash
# 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:**
```bash
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:**
```bash
# 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:**
```bash
stella admin system status [--format <format>] [--verbose]
```

**Options:**
- `--format <format>` - Output format: `table` (default), `json`

**Examples:**
```bash
# 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:**
```bash
stella admin system info [--verbose]
```

**Examples:**
```bash
stella admin system info
```

---

## Configuration

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

```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:
```bash
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:
```bash
export STELLAOPS_BACKEND__BASEURL="https://api.stellaops.example.com"
stella admin system status
```

## See Also

- [CLI Reference](../09_API_CLI_REFERENCE.md)
- [Authority Documentation](../11_AUTHORITY.md)
- [Operational Procedures](../operations/administration.md)