Maintenance & License•6 min read•CLI

CLI Commands & System Control (ciel)

Manage CIEL from the terminal using the standalone ciel CLI utility for system health diagnostics, service daemon lifecycle, user administration, licensing, and database maintenance.

In addition to the web dashboard, CIEL provides a standalone command-line executable (ciel). The CLI allows system administrators to inspect host dependencies, automate service daemons via systemd, manage user credentials directly from the shell, and create atomic database backups without opening a web browser.


1. System Health Diagnostics (ciel doctor)

Before starting the server or troubleshooting environment issues, run ciel doctor (or ciel check) to verify subsystem health and host requirements:

Terminal(bash)
ciel doctor

The diagnostic engine executes nine automated checks against your host environment:

  1. Python Runtime: Confirms Python >= 3.11 and detects whether CIEL is running as a compiled standalone binary or via an active virtual environment.
  2. Ansible Core: Verifies that the ansible CLI is installed and detects the version for native playbook execution.
  3. Ansible Runner: Validates the presence of ansible-runner for streaming job execution and process isolation.
  4. Podman Container Engine: Inspects whether Podman is installed to support isolated container runner environments.
  5. Filesystem Permissions: Tests read and write operations across Controller Home, Runner Root, Log Directory, and Workspace Root.
  6. Database Connectivity: Establishes a live connection to the configured SQLite database or PostgreSQL cluster.
  7. Secrets & Security Configuration: Inspects .ciel_secret file permissions (recommending 0600) and guards against default development JWT secrets.
  8. Licensing Status: Inspects the active edition (Community or Enterprise), displays the unique Hardware ID (HWID), and verifies license validity.
  9. Port Availability: Checks whether default port 8137 is available for binding or already bound by an active CIEL instance.

Sample Diagnostic Output

text
CIEL Controller Health & Readiness Doctor
─────────────────────────────────────────
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component            ┃ Status / Details      ┃ Result ┃ Notes                ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ Python Runtime       │ 3.11.x (Python        │ PASS   │ >= 3.11              │
│                      │ Interpreter)          │        │                      │
│ Ansible Core         │ ansible [core 2.16.x] │ PASS   │ Native execution     │
│ Ansible Runner       │ 2.4.3                 │ PASS   │ Job execution engine │
│ Podman Container     │ podman version 4.x    │ PASS   │ Execution            │
│ Engine               │                       │        │ environments         │
│ Dir: Controller Home │ /var/lib/ciel         │ PASS   │ Read/Write OK        │
│ Dir: Runner Root     │ /var/lib/ciel/runner  │ PASS   │ Read/Write OK        │
│ Dir: Log Directory   │ /var/log/ciel         │ PASS   │ Read/Write OK        │
│ Dir: Workspace Root  │ /var/lib/ciel/work    │ PASS   │ Read/Write OK        │
│ Database Connection  │ sqlite:///...         │ PASS   │ Connected            │
│                      │                       │        │ successfully         │
│ Secrets & Security   │ Persistent (0600)     │ PASS   │ Secrets securely     │
│                      │                       │        │ stored in            │
│                      │                       │        │ .ciel_secret         │
│ Licensing Edition    │ Enterprise (ID: ...)  │ PASS   │ Valid: True          │
│ Port 8137            │ Available             │ PASS   │ Ready for binding    │
└──────────────────────┴───────────────────────┴────────┴──────────────────────┘
[OK] All system readiness checks passed!

2. Server Setup & Daemon Management

ciel start and ciel run perform the initial bootstrap automatically. On first launch, CIEL creates its directory structure, applies database migrations, and creates the initial administrator from the configured CIEL_BOOTSTRAP_ADMIN_* environment variables. If no password is configured, CIEL generates one and prints it during startup.

Server Lifecycle Control

Terminal(bash)
# Run server interactively in foreground (useful for development and live log debugging)
ciel run --host 0.0.0.0 --port 8137

# Enable hot-reloading during development
ciel run --reload

# Start the background daemon process
ciel start --host 0.0.0.0 --port 8137

# Inspect background service status, active PID, and listening endpoint
ciel status

# Gracefully stop the background daemon (sends SIGTERM, followed by SIGKILL after timeout)
ciel stop --timeout 15

# Restart the running daemon
ciel restart --host 0.0.0.0 --port 8137

When started as a background daemon, CIEL writes its process ID to $CIEL_HOME/ciel.pid and redirects operational logs to $CIEL_HOME/logs/ciel.log.


3. Systemd Service Registration (ciel systemd)

To run CIEL automatically on Linux system boot:

Generate Systemd Service Unit

Generate a standard systemd service unit tailored to your current user and path:

Terminal(bash)
# Print generated unit file to stdout
ciel systemd generate

# Save unit file directly to a custom path
ciel systemd generate --user ciel --output /tmp/ciel.service

Install and Enable Service

Install the unit file directly into the system systemd directory:

Terminal(bash)
# Installs to /etc/systemd/system/ciel.service, reloads daemon, and enables on boot
sudo ciel systemd install

# Check service status using systemctl
systemctl status ciel

# Follow live system logs
journalctl -u ciel -f

4. User & Administrator Management (ciel admin)

Manage user accounts and reset lost credentials directly from the host terminal:

Terminal(bash)
# List all registered user accounts
ciel admin list

# Create a new administrator account
ciel admin create --username opsadmin --email [email protected] --password "[REDACTED]" --role admin

# Create an operator or viewer account
ciel admin create --username devoperator --email [email protected] --role operator

# Reset an existing user password
ciel admin reset-password --username admin --password "[REDACTED]"

If --password is omitted, the CLI provides interactive masked prompts with password confirmation or generates a one-time password automatically.


5. Commercial License Management (ciel license)

Inspect resource quotas, activate commercial licenses, and query machine Hardware IDs (HWID):

Terminal(bash)
# View active license tier, expiration date, and quota consumption
ciel license status

# Display the unique Hardware ID (HWID) for node-locking
ciel license hwid

# Activate a commercial license via signed Ed25519 token string
ciel license activate "CIEL-V1.pro.eyJhZGRvbnMi...signature"

# Activate a commercial license from a file path
ciel license activate /etc/ciel/license.lic

# Deactivate commercial license and revert to Community edition limits
ciel license deactivate

Quota Tracking

Running ciel license status displays real-time resource utilization against license limits:

  • Managed Hosts: Number of active hosts registered across all projects.
  • Projects: Total configured team projects.
  • Provisioners & Monthly Runs: Active zero-touch bootstrap endpoints and monthly trigger volume.
  • Webhooks & Monthly Triggers: Inbound CI/CD trigger endpoints and execution counts.

6. Database Maintenance & Backups (ciel db)

CIEL provides built-in database management commands for schema migration and atomic backups:

Terminal(bash)
# Initialize database tables and run pending migrations to head
ciel db init

# Create an atomic point-in-time backup snapshot
ciel db backup

# Specify a custom destination path for the backup file
ciel db backup --output /var/backups/ciel/ciel_snapshot_$(date +%F).db

# Restore database from a backup snapshot
ciel db restore /var/backups/ciel/ciel_snapshot_2026-11-05.db --force
Note

ciel db backup utilizes the SQLite Online Backup API. It creates consistent, uncorrupted database snapshots without requiring the server daemon to be stopped or paused.


7. Model Context Protocol Server (ciel mcp)

Start the native Model Context Protocol (MCP) server over standard input/output (stdio) to connect AI coding assistants (such as Claude Code, Cursor, and Hermes Agent) directly to your controller:

Terminal(bash)
# Start MCP server over stdio with default local controller (http://127.0.0.1:8137)
ciel mcp

# Override API endpoint for remote or containerized controller instances
ciel mcp --api-url https://ciel.internal.company.com:8137

# Specify a custom environment credentials file
ciel mcp --env-file ~/.ciel/.env

For detailed client configuration examples, safety tier models, and integration patterns, see Model Context Protocol (MCP) Integration.


8. Version Inspection (ciel version)

Inspect the currently installed CIEL controller binary version and build revision:

Terminal(bash)
# Print version via subcommand
ciel version

# Or inspect via standard version flags
ciel --version
ciel -V

9. External References

For upstream specifications on systemd services, Ansible execution, and database backups: