CLI & Flags Reference
Comprehensive reference manual for all command-line operations, interactive utilities, and configuration flags.
1. Command Dispatcher
The cicd binary can be executed with specific commands for project management, logging, diagnostics, and recovery. Run these directly in your terminal:
| Command | Usage | Description |
|---|---|---|
list / ls |
cicd list |
Lists all registered services on the system, their deployment status, and current active commit hashes. |
info |
cicd info |
Prints setup details for the Command Center, including access tokens, API urls, webhook endpoints, and guide links. |
status |
cicd status |
Checks if the systemd background daemon is running, active, and loaded. |
start |
cicd start |
Launches or starts the background orchestrator systemd service. |
stop |
cicd stop |
Halts the background orchestrator service. |
restart |
cicd restart |
Restarts the background orchestrator service to apply updates. |
logs / log |
cicd log [service] |
Tails the live stdout/stderr logs. Run without args for system logs, or specify a project slug (e.g. cicd log my-app). |
token |
cicd token [--force] |
Retrieves the current onboarding token. Add --force to regenerate a new secure token. |
pin |
cicd pin <service> <hash> |
Pins a service deployment to a specific commit. Webhooks will log incoming push events but skip builds. |
unpin |
cicd unpin <service> |
Removes pin constraints from a service, enabling webhook deployments again. |
history |
cicd history <service> |
Displays the deployment history list, timestamps, status, and authors. |
rollback |
cicd rollback <service> <hash> |
Rolls back the environment state to a previous commit. Skips the install.sh hash check to force environment re-evaluation. |
reinstall |
cicd reinstall <service> |
Forces a clean environment reinstall by executing install.sh, bypassing the hash cache. |
doctor |
cicd doctor |
Runs automated system-level diagnostic health checks on ports, SQLite database connection (/etc/cicd/data/cicd.db), and SMTP availability. |
uninstall |
cicd uninstall |
Safely stops the service daemon, disables it from startup, and cleans up configurations. |
help |
cicd help |
Prints a formatted guide of all commands. |
2. Orchestrator Flags
All flags are optional. Running the binary without flags launches the multi-project orchestrator daemon on the default port 9641. If --repo-url is passed, the binary registers/configures that project first before starting the background daemon listener.
| Flag | Default | Description |
|---|---|---|
--repo-url |
— | Target Git repository URL to clone and monitor. Passing this enters project configuration mode. |
--branch |
main |
The repository branch to watch for push events. |
--webhook |
9641 |
The TCP port for the webhook listener and Command Center API/Dashboard. |
--webhook-secret |
auto-generated | Secure signature token for verifying incoming payloads (HMAC-SHA256). |
--admin-email |
— | Email address to receive alerts. **Requires SMTP credentials to be set up.** |
--public-ip |
auto-detected | Manual override for the public IP address (useful for local dev with 127.0.0.1). |
--git-username |
— | Username for accessing private repositories. |
--git-password |
— | Token or password for accessing private repositories. |
--service-name |
mycicdapp |
Unique identifier slug for this project (letters, numbers, hyphens). |
--service-dir |
/home/ |
Base system directory under which the sandboxed user home is generated. |
--service-user |
auto-generated | Pre-existing system username to run as, overriding the auto-provisioned sandboxed user. |
--mongodb-uri |
— | MongoDB Atlas connection string to sync fleet state across multiple servers. |
--smtp-host |
— | SMTP server host for sending email notifications. |
--smtp-port |
587 |
SMTP port for email alerts. |
--smtp-user |
— | SMTP username credentials. |
--smtp-pass |
— | SMTP password credentials. |
--notify-url |
— | Slack, Discord, or generic Webhook URL for real-time channel deployment alerts. |
--deploy-timeout |
1800 |
Global timeout in seconds for executing install.sh. (default: 30 minutes). |
--setup |
— | Set to run to test the orchestrator directly in the foreground (skips systemd setup). |
--service-reset |
false |
Re-writes systemd unit files and updates daemon configurations. |