Everything Protocol can do, organized by what you're trying to accomplish. Run protocol <command> --help on any command for the full details.
These are the commands you'll use every day.
Set up a new project or update an existing one. A wizard walks you through it.
protocol initIf it's a new project, you pick your Docker image, choose a deploy strategy, and optionally set up secrets and a config repo. If you've already set up, it offers to fix/migrate, change strategy, or set up secrets.
Safe to re-run anytime — it detects what's already there.
Start everything. This is the one command that makes it all work.
protocol startRuns through eight stages — scanning your codebase, provisioning infrastructure, building containers, running post-start hooks, running a security audit, checking SOC 2 readiness, verifying health, and checking disk space. Each stage shows its progress and collapses to OK, PASS, or FAIL:
[protocol] Scanning codebase.............. OK
[protocol] Infrastructure provisioning.... OK
[protocol] Container build & start........ OK
[protocol] Post-start hooks............... OK
[protocol] Running security audit......... PASS
[protocol] SOC 2 readiness check.......... PASS
[protocol] Health checks.................. PASS
[protocol] Disk space check............... OK
✓ Deployment complete. All systems operational.
Environment production
Strategy release (v1.2.0)
Secrets decrypted
Containers 3/3 running
Watchers release watcher running
Crontab installed
Completed in 12.3s
The summary confirms your environment, whether secrets were decrypted, how many containers are up, whether watchers are active, and crontab status. If a stage fails, it shows the error detail below the FAIL line and continues to the next stage. In CI/CD environments (non-TTY), the output drops the ANSI formatting automatically.
Stop everything. Kills watchers, unlinks configs, stops Docker containers, removes the reboot cron entry.
protocol stopSame staged output as protocol start — five stages with verification at the end:
[protocol] Stopping watchers.............. OK
[protocol] Unlinking configuration........ OK
[protocol] Stopping containers............ OK
[protocol] Removing crontab entry......... OK
[protocol] Verifying shutdown............. PASS
✓ Shutdown complete. All services stopped.
Environment production
Containers 3/3 stopped
Watchers stopped
Crontab removed
Completed in 3.1s
See what's going on. Shows your deploy strategy, current version, running watchers, Docker containers, and whether everything looks healthy.
protocol statusStop and start again. Designed for @reboot crontab entries so your app survives server restarts.
protocol restartCreating and managing versioned releases of your code.
Tag a new release. Writes a VERSION file, creates a git tag, pushes it, and creates a GitHub Release.
protocol release:create # auto-bumps patch (1.0.0 → 1.0.1)
protocol release:create 2.0.0 # specific version
protocol release:create --minor # bumps minor (1.0.1 → 1.1.0)
protocol release:create --major # bumps major (1.1.0 → 2.0.0)
protocol release:create --draft # creates as draft releaseSee all your releases. The currently deployed version gets a * next to it.
protocol release:listPrepare the codebase for the next release. Runs any pre-release tasks.
protocol release:prepareGenerate a CHANGELOG.md file from your git history.
protocol release:changelogPushing releases to your fleet and rolling back when things go wrong.
View or change the deployment strategy.
protocol deploy:strategy # show current strategy
protocol deploy:strategy release # switch to release mode
protocol deploy:strategy bluegreen # switch to blue-green mode
protocol deploy:strategy branch # switch to branch modeAfter changing strategy, run protocol restart to activate the new watcher.
Deploy a release to ALL nodes. Sets the GitHub variable that every node watches.
protocol deploy:push 1.2.0Every node running protocol start will pick this up within 60 seconds and deploy automatically.
Undo the last deploy. Sets the pointer back to the previous version. Every node follows.
protocol deploy:rollbackCheck if your nodes are in sync. Shows the active release (what GitHub says) vs. the local version (what this node is running).
protocol deploy:statusView the deployment audit trail. Every deploy and rollback is logged with timestamps and version transitions.
protocol deploy:log
protocol deploy:log --limit=50 # show more entriesDeploy a specific version on THIS node only. Useful for testing a release on staging before pushing it to everyone.
protocol node:deploy 1.2.0 # on your staging serverRoll back THIS node only.
protocol node:rollbackStart the release watcher daemon. Polls the GitHub variable for active release changes and deploys automatically. Used internally by protocol start in release mode.
protocol deploy:slave
protocol deploy:slave --interval=30 # poll every 30 seconds
protocol deploy:slave --no-daemon # run in foreground (debugging)Stop the release watcher daemon.
protocol deploy:slave:stopZero-downtime deployments using shadow directories. Each release gets its own directory with a full git clone, Docker containers, and config files. Traffic is swapped instantly when the new version is healthy.
Initialize shadow deployment configuration for your project.
protocol shadow:initBuild a release version in a shadow directory. Clones the repo, checks out the version, sets up Docker, and runs health checks.
protocol shadow:build v1.2.0
protocol shadow:build v1.2.0 --skip-health-checkPromote the shadow version to production by swapping ports.
protocol shadow:startRoll back to the previous version instantly by swapping ports back.
protocol shadow:rollbackShow shadow deployment status — which version is active, which is standby, health state.
protocol shadow:status
protocol shadow:status --json # raw JSON outputManaging your encryption key and encrypted files.
Generate a new encryption key or store one from another node.
protocol secrets:setup # generate new key
protocol secrets:setup "your-64-char-hex-key" # store existing keyThe key is saved at ~/.protocol/.node/key with strict permissions. Run this once per machine.
In CI/CD, it also reads from the PROTOCOL_ENCRYPTION_KEY environment variable automatically.
View your encryption key and all the ways to transfer it to other machines.
protocol secrets:key # show key + transfer options
protocol secrets:key --raw # just the key (for scripting)
protocol secrets:key --push # push to GitHub as a secret
protocol secrets:key --scp=deploy@prod-server # SCP to a remote nodeEncrypt .env files in your config repo.
protocol secrets:encrypt # encrypts .env → .env.enc
protocol secrets:encrypt myfile.env # encrypt a specific fileDecrypt and display an encrypted file. For debugging — secrets are decrypted automatically during protocol start.
protocol secrets:decryptManaging your config repo and environment-specific files.
The config wizard. Creates your config repo, encrypts or decrypts secrets, or re-initializes from scratch.
protocol config:initIf a config repo already exists, it shows you a smart menu — recommending encrypt if you have unencrypted .env files, or decrypt if you have encrypted files but no key on this machine.
Set this machine's environment name. This determines which branch of the config repo gets used.
protocol config:env production
protocol config:env localhost-sarahMove a file from your project into the config repo. Creates a symlink back so your app still finds it.
protocol config:mv .env
protocol config:mv nginx.confAlso adds the file to .gitignore in your project.
Create all the symlinks from your config repo into your project. Happens automatically during protocol start, but you can run it manually.
protocol config:linkRemove all config symlinks.
protocol config:unlinkSwitch to a different environment. Saves current changes, unlinks, switches the branch, and re-links.
protocol config:switch staging
protocol config:switch productionCommit and push changes in your config repo.
protocol config:saveCopy a file into the config repo without removing it from your project (unlike config:mv which moves it).
protocol config:cp nginx.confCreate a new configuration repository from scratch.
protocol config:newClear all config symlinks and rebuild them. Useful if symlinks get out of sync.
protocol config:refreshKeep the config repo in sync with its remote. Polls for changes and pulls automatically.
protocol config:slave
protocol config:slave --increment=30 # poll every 30 seconds
protocol config:slave --no-daemon # run in foregroundUsed internally by protocol start. You rarely need to run this directly.
Stop the config repo watcher.
protocol config:slave:stopManaging your containers.
Start your Docker containers. In encrypted mode, decrypts secrets and injects them.
protocol docker:composeRebuild and restart containers. Use this after changing your Dockerfile or docker-compose.yml.
protocol docker:compose:rebuildStop and remove containers.
protocol docker:compose:downRun a command inside your container. Opens a bash shell if you don't specify a command.
protocol docker:exec # opens bash
protocol docker:exec "php artisan migrate" # run a specific commandFollow your container's logs.
protocol docker:logsBuild the Docker image from a local Dockerfile source.
protocol docker:buildPull the Docker image from the registry, or build it if a local Dockerfile is configured.
protocol docker:pullPush the Docker image to the remote registry.
protocol docker:pushAudit all Docker containers, images, and volumes. Shows age, status, and disk usage with color-coded age indicators.
protocol docker:statusPrune stopped containers and unused images. Pass full to also wipe unused volumes. Also cleans up old release directories in blue-green mode.
protocol docker:cleanup # safe mode (containers, images, networks, cache)
protocol docker:cleanup full # also prune unused volumesEnable or disable scheduled Docker cleanup via cron.
protocol docker:cleanup:schedule on # enable daily at 3am
protocol docker:cleanup:schedule on --cron="0 6 * *" # custom schedule
protocol docker:cleanup:schedule off # disable
protocol docker:cleanup:schedule status # check current stateRun composer install inside the Docker container.
protocol composer:installManage Protocol's extensible plugin system. Plugins add commands for integrations like Cloudflare, AWS Secrets, and Sulla.
List all available plugins and their status.
protocol plugin:listEnable a plugin globally. Verifies credentials/tooling if the plugin requires it.
protocol plugin:enable cloudflare
protocol plugin:enable awssecretsDisable a plugin globally. Can be re-enabled later without reconfiguration.
protocol plugin:disable cloudflareRun commands automatically after protocol start finishes bringing up containers. Useful for dependency installs, cache warming, queue restarts, or any post-deploy task.
Hooks are stored in protocol.json under lifecycle.post_start and run in order during Stage 4 of protocol start. For release/bluegreen deployments, hooks execute inside the active release directory.
Show all configured post-start hooks.
protocol lifecycle list Post-start hooks:
[0] exec:app composer install --no-interaction --no-dev --optimize-autoloader
[1] exec:worker php artisan queue:restart
Append a hook to the list.
protocol lifecycle add "exec:app composer install --no-interaction"Two formats:
| Format | Runs where | Example |
|---|---|---|
exec:<service> <command> |
Inside the named docker compose service | exec:app composer install |
<command> |
On the host | echo "deploy complete" |
The <service> name matches the service key in your docker-compose.yml (e.g., app, worker, redis).
Remove a hook by its index (shown in list output).
protocol lifecycle remove 0Remove all hooks.
protocol lifecycle clearHooks are stored in protocol.json:
{
"lifecycle": {
"post_start": [
"exec:app composer install --no-interaction --no-dev --optimize-autoloader",
"exec:worker php artisan queue:restart",
"echo deployment complete"
]
}
}You can edit this file directly or use the protocol lifecycle commands above.
Commands for auditing your codebase and verifying SOC 2 readiness.
Run a security scan against your codebase and server. Checks for malicious code patterns, file permission issues, dependency vulnerabilities, suspicious processes, Docker misconfigurations, and unauthorized file changes.
protocol security:auditResults are displayed in a table with PASS/WARN/FAIL for each check. This runs automatically during protocol start, but you can run it anytime on its own.
Validate your setup against SOC 2 Type II requirements. Checks that secrets are encrypted, audit logging is active, you're using release-based deployment, git integrity is maintained, reboot recovery is configured, and key permissions are correct.
protocol soc2:checkSame table format as the security audit. Also runs automatically during protocol start.
Deep scan for trojan patterns in PHP files. Looks for obfuscated code, backdoors, and known malicious patterns like eval(base64_decode(...)).
protocol security:trojansearchList files that have been modified recently. Useful for spotting unauthorized changes on production nodes.
protocol security:changedfiles
protocol security:changedfiles --days=7 # look back 7 daysLive incident dashboard. Shows all detected issues, container health, logged-in users, changed files, recently modified files, and recently added files. Refreshes every 5 seconds. Use this as your first command when Protocol alerts you to an incident.
protocol incident:status
protocol incident:status --once # run once and exit
protocol incident:status --interval=10 # refresh every 10 secondsWhen Protocol detects a P1 or P2 incident, every command will show an alert banner directing you to run protocol incident:status.
Create a full incident report. Gathers all available system state — deployment logs, security audit results, SOC 2 check results, container status, process list, network connections — and compiles a structured report. Opens a GitHub issue and sends notifications to configured webhooks.
# Severity auto-detected from system state:
protocol incident:report "Unauthorized deploy detected at 3am"
# Override severity (1-4 or P1-P4):
protocol incident:report 1 "SIEM alert: file integrity change"
protocol incident:report P2 "Degraded service on node-3"
protocol incident:report 3 "Dependency CVE discovered" --no-issueSeverity levels:
- P1 — Security audit failures or multiple containers down
- P2 — SOC 2 check failures or single container down
- P3 — Warnings from audits or checks
- P4 — Informational, no failures detected
The report is saved to ~/.protocol/.node/incidents/, a forensic snapshot is automatically captured, a GitHub issue is created, everything is logged to the audit trail, and notifications are sent to all configured webhook URLs in protocol.json.
Capture a forensic snapshot of the entire system state. Run this immediately during triage — before any containment or remediation. It preserves everything needed for forensic analysis.
protocol incident:snapshotCaptures: audit logs, running processes, network connections, Docker container state and logs, git history and diffs, system info, crontab, SIEM status, auth logs, and recently modified files. All saved to ~/.protocol/.node/incidents/snapshot-YYYY-MM-DD-HHMMSS/ with 0700 permissions.
Install and configure the Wazuh SIEM agent for centralized security monitoring. Sets up file integrity monitoring for ~/.protocol/.node/ and forwards audit logs to your SIEM.
protocol siem:install --manager=wazuh.example.com
protocol siem:install --manager=10.0.0.5 --password=secret --agent-name=prod-1
protocol siem:install --uninstallCheck the health of the Wazuh SIEM agent on this node.
protocol siem:statusReal-time dashboards for debugging and breach detection.
Real-time system command center. Shows processes, network connections, Docker containers, and security status in a continuously updating display.
protocol top
protocol top --interval=10 # refresh every 10 seconds
protocol top --once # run once and exitVisual dashboard of all Docker containers and shadow deployments across release directories.
protocol top:shadow
protocol top:shadow --interval=10
protocol top:shadow --onceLow-level git operations that Protocol wraps for convenience.
Pull from the remote and update the local repo.
protocol git:pullIf your .git folder is bloating, this runs garbage collection and pruning to reclaim space.
protocol git:cleanStart the branch-mode continuous deployment watcher. Polls the remote for changes and pulls automatically.
protocol git:slave
protocol git:slave --increment=30 # poll every 30 seconds
protocol git:slave --no-daemon # run in foregroundUsed internally by protocol start in branch mode. You rarely need to run this directly.
Stop the branch-mode watcher.
protocol git:slave:stopHousekeeping and setup commands.
| Command | What it does |
|---|---|
protocol self:update |
Update Protocol to the latest release |
protocol self:update --nightly |
Update to the latest commit (bleeding edge) |
protocol self:global |
Install Protocol as a global command (symlink to /usr/local/bin) |
protocol cron:add |
Add a @reboot crontab entry so Protocol restarts after reboots |
protocol cron:remove |
Remove the crontab entry |
protocol key:generate |
Generate an SSH deploy key for pulling from private repos |
protocol nginx:logs |
Tail nginx and PHP-FPM logs from inside the container |
protocol migrate |
Interactive wizard to convert from branch-based to release-based deployment |
protocol open |
Open the current project in the browser (detects running container ports) |
| What you want to do | Command |
|---|---|
| Set up a new project | protocol init |
| Start everything | protocol start |
| Stop everything | protocol stop |
| Check what's running | protocol status |
| Create a release | protocol release:create |
| Deploy to all nodes | protocol deploy:push 1.2.0 |
| Roll back | protocol deploy:rollback |
| Zero-downtime deploy | protocol shadow:build v1.2.0 then protocol shadow:start |
| Shadow rollback (instant) | protocol shadow:rollback |
| Set up configs & secrets | protocol config:init |
| Run a command in Docker | protocol docker:exec "your command" |
| View your encryption key | protocol secrets:key |
| Run a security scan | protocol security:audit |
| Check SOC 2 readiness | protocol soc2:check |
| Install SIEM agent | protocol siem:install --manager=host |
| View incident dashboard | protocol incident:status |
| Report an incident | protocol incident:report 1 "msg" |
| Capture forensic snapshot | protocol incident:snapshot |
| Real-time monitoring | protocol top |
| Change deploy strategy | protocol deploy:strategy release |
| Audit Docker resources | protocol docker:status |
| Clean up Docker | protocol docker:cleanup |
| Manage plugins | protocol plugin:list |
| Open project in browser | protocol open |
| Update Protocol itself | protocol self:update |