ccs/docs/dashboard-auth-cli.md

Dashboard Authentication CLI

CLI commands for managing CCS dashboard authentication.

Overview

The CCS dashboard (ccs config) can be protected with username/password authentication. This is useful when running the dashboard on a network-accessible machine.

Authentication is disabled by default for backward compatibility. Use the CLI to configure and enable it.

Commands

ccs config auth setup

Interactive wizard to configure dashboard login.

$ ccs config auth setup

╭─────────────────────────────────╮
│  Dashboard Auth Setup           │
╰─────────────────────────────────╯

[i] Configure username and password for dashboard access.
    Password will be hashed with bcrypt before storage.

Username
Enter username: admin

Password
    Minimum 8 characters
Enter password: ********
Confirm password: ********

[i] Hashing password...

[OK] Dashboard authentication configured

[i] Settings saved to ~/.ccs/config.yaml
[i] Username: admin
[i] Session timeout: 24 hours

    Start dashboard: ccs config
    Show status: ccs config auth show
    Disable auth: ccs config auth disable

ccs config auth show

Display current authentication status.

$ ccs config auth show

╭─────────────────────────────────╮
│  Dashboard Auth Status          │
╰─────────────────────────────────╯

Configuration
[OK] Authentication: Enabled
[OK] Username: admin
[i] Session timeout: 24 hours

Commands
  ccs config auth setup     Configure authentication
  ccs config auth disable   Disable authentication
  ccs config                Open dashboard

ccs config auth disable

Disable dashboard authentication with confirmation.

$ ccs config auth disable

╭─────────────────────────────────╮
│  Disable Dashboard Auth         │
╰─────────────────────────────────╯

[!] This will disable login protection for the dashboard.
[i] Anyone with network access will be able to view the dashboard.

Disable authentication? [y/N]: y

[OK] Dashboard authentication disabled

[i] Credentials preserved - re-enable with: ccs config auth setup

ccs config auth --help

Display usage information.

Environment Variables

Environment variables override config.yaml values:

Variable	Description
CCS_DASHBOARD_AUTH_ENABLED	Enable/disable auth (true/false)
CCS_DASHBOARD_USERNAME	Username
CCS_DASHBOARD_PASSWORD_HASH	Bcrypt password hash

Generating a Password Hash

Use bcrypt to generate a hash:

# Using Node.js
node -e "console.log(require('bcrypt').hashSync('your-password', 10))"

# Using npx
npx bcrypt-cli hash "your-password"

Configuration

Settings are stored in ~/.ccs/config.yaml:

# Dashboard Auth: Optional login protection for CCS dashboard
# Generate password hash: npx bcrypt-cli hash "your-password"
# ENV override: CCS_DASHBOARD_AUTH_ENABLED, CCS_DASHBOARD_USERNAME, CCS_DASHBOARD_PASSWORD_HASH
dashboard_auth:
  enabled: true
  username: "admin"
  password_hash: "$2b$10$..."
  session_timeout_hours: 24

Security Notes

1. Bcrypt hashing: Passwords are hashed with bcrypt (10 rounds) before storage
2. Session cookies: Sessions use HTTP-only cookies (not accessible via JavaScript)
3. Rate limiting: Login attempts are rate-limited (5 per 15 minutes)
4. File permissions: Config file is created with 0o600 permissions

Troubleshooting

"Authentication not configured"

Run ccs config auth setup to configure credentials.

Forgot password

Run ccs config auth setup again to set a new password.

ENV override not working

Ensure the variable is exported:

export CCS_DASHBOARD_AUTH_ENABLED=true
export CCS_DASHBOARD_USERNAME=admin
export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$...'

Session expired immediately

Check session_timeout_hours in config. Default is 24 hours.

See Also

• Dashboard Auth Feature - Full documentation
• Config Schema - All config options