Skip to main content

Useful Cake Commands

Reference for Passbolt cake commands used for maintenance, troubleshooting, and administration.

Running Commands​

The command syntax varies depending on your installation method. Replace $command in the examples below with the actual command (e.g., passbolt healthcheck, cache clear_all).

Debian-based Systems​

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake $command" www-data

RPM-based Systems​

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake $command" nginx

Docker (from host)​

docker compose exec passbolt su -s /bin/bash -c "source /etc/environment && ./bin/cake $command" www-data

Docker (inside container)​

su -s /bin/bash -c "source /etc/environment && ./bin/cake $command" www-data

Docker Rootless (from host)​

docker compose exec passbolt ./bin/cake $command

Docker Rootless (inside container)​

./bin/cake $command
info

When running commands interactively inside a Docker container, source environment variables first:

source /etc/environment

The Docker commands above already include this.

System Health and Diagnostics​

Healthcheck​

Checks system configuration and health: GPG, TLS (SSL), database, and application settings.

Options:

  • --hide-pass - Hide passing checks (useful for cleaner output)
  • --hide-warning - Hide warnings
  • --hide-help - Hide help messages
  • --hide-title - Hide section titles
  • --hide-notice - Hide info messages
  • --database - Run database checks only
  • --gpg - Run GPG checks only
  • --application - Run application checks only
  • --ssl - Run TLS (SSL) checks only
  • --environment - Run environment checks only
  • --configFiles - Run config file checks only
  • --core - Run core config checks only
  • --smtpSettings - Run SMTP settings checks only
  • --jwt - Run JWT authentication checks only
  • --metadata - Run metadata checks only
  • --posix - Set the exit status to 1 when errors or warnings are detected, and print them to STDERR (useful for scripts and CI)
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt healthcheck" www-data

Examples:

# Clean output - hide passing checks
./bin/cake passbolt healthcheck --hide-pass

# Only database checks
./bin/cake passbolt healthcheck --database

# Multiple check types
./bin/cake passbolt healthcheck --database --gpg
tip

Read-only. Use --posix to make the exit code reflect errors and warnings, useful for CI.

Datacheck​

Validates data integrity: GPG keys, authentication tokens, groups, resources, and other database entities.

What it checks:

  • Authentication tokens integrity
  • Comments validity
  • Favorites consistency
  • GPG keys validation
  • Groups data
  • Profiles completeness
  • Resources integrity
  • Secrets consistency
  • Users data validity
  • Metadata (if V5 enabled)

Options:

  • --hide-success-details - Hide details of passing checks
  • --hide-error-details - Hide details of failing checks
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt datacheck" www-data

Examples:

# Clean output - only show failures
./bin/cake passbolt datacheck --hide-success-details

# Very quiet - only summary
./bin/cake passbolt datacheck --hide-success-details --hide-error-details
tip

Read-only. Can be slow on large datasets.

Status Report​

Runs healthcheck, cleanup (dry-run), datacheck, and shows the last 100 lines of error logs.

What it does:

  • Displays version information
  • Runs healthcheck (passbolt healthcheck)
  • Runs cleanup check in dry-run mode (passbolt cleanup --dry-run)
  • Runs data validation (passbolt datacheck --hide-success-details)
  • Shows last 100 lines of error logs
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/status-report" www-data
./bin/status-report > diagnostic_report.txt

Show Logs Path​

Shows the path to Passbolt log files.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt show_logs_path" www-data

Version​

Shows the installed Passbolt version.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt version" www-data

Data Maintenance​

Cleanup​

Identifies and fixes database relational integrity issues.

warning

IMPORTANT: Always run with --dry-run first to preview changes!

What it cleans:

  • Groups with no members
  • GroupsUsers for soft/hard deleted users and groups
  • Favorites for soft/hard deleted users and resources
  • Comments for soft/hard deleted users and resources
  • Permissions for soft/hard deleted users, groups, and resources
  • Secrets for soft/hard deleted users, resources, and permissions
  • Resources with missing ResourceType ID
  • Avatars for soft/hard deleted users and profiles
  • Users: inactive users with duplicated username

Prerequisites:

  • Requires users table to exist
  • Requires at least one active administrator

Options:

  • --dry-run - Preview issues without fixing (default: true)

Dry-run (recommended first):

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt cleanup --dry-run" www-data

Run cleanup:

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt cleanup" www-data
info

Default is --dry-run=true. Aborts if no admin users exist or users table is missing.

Truncate Account Recovery Tables​

danger

DESTRUCTIVE: This command truncates all account recovery tables. This deletes ALL account recovery data and cannot be undone!

Clears all account recovery tables. Use to reset the account recovery process.

Tables truncated:

  • account_recovery_organization_policies
  • account_recovery_organization_public_keys
  • account_recovery_private_key_passwords
  • account_recovery_private_keys
  • account_recovery_requests
  • account_recovery_responses
  • account_recovery_user_settings

Options:

  • -u, --username - Admin username for verification (optional)
  • -f, --fingerprint - Organisation public key fingerprint for verification (optional)
  • -n, --no-verify - Skip all verification checks (dangerous!)

Interactive mode (default):

  • Prompts for admin username verification
  • Prompts for fingerprint verification
  • Asks for confirmation before truncating
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt truncate_account_recovery_tables" www-data

Examples:

# Interactive mode (recommended - safest)
./bin/cake passbolt truncate_account_recovery_tables

# Non-interactive with verification
./bin/cake passbolt truncate_account_recovery_tables \
  -u [email protected] \
  -f 2FC8B1DD1EA5BB8FBBFBA86F8F0DB86DD4FD9C70
info

Enterprise Edition only.

Action Logs Purge​

Removes old entries from the action logs table. Specify retention period in days with -r.

warning

Performance may be degraded while running. Always run with --dry-run first.

Options:

  • -r, --retention-in-days - Days to retain logs (required, must be > 0)
  • -l, --limit - Batch size (default: 100000)
  • -d, --dry-run - Preview without deleting (recommended first run)
  • -v, --verbose - Show count of logs grouped by action

Dry-run (recommended first):

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt action_logs_purge --dry-run -r 90" www-data

Purge action logs (example: 90 days retention):

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt action_logs_purge -r 90" www-data

Examples:

# Preview purge (90 day retention)
./bin/cake passbolt action_logs_purge -r 90 --dry-run

# Actually purge with verbose output
./bin/cake passbolt action_logs_purge -r 90 -v

# Purge with custom batch size (for large datasets)
./bin/cake passbolt action_logs_purge -r 90 -l 50000
info

Processes in batches. Can be scheduled via cron.

Restore an SQL Backup​

Loads an SQL backup back into the database, as the counterpart of the sql_export used to produce it.

Options:

  • --file - The SQL file to import
  • --dir - The directory holding the file (default: the tmp/cache/database/ directory of the installation)
  • -d, --datasource - Datasource name (default: default)

Pass --file explicitly: without it, the command takes the first file in reverse alphabetical order from the directory, which is not necessarily the most recent backup. Note that the export and the import are not symmetric under the hood: sql_export calls a database client binary, while this command loads the file through the application's database connection, so it needs no client binary but reads the whole dump into memory.

For the full procedure, including the restore-specific precautions and the command for your installation type, see backup and recovery.

Email Management​

Send Test Email​

Sends a test email to verify SMTP configuration.

Options:

  • -r, --recipient - Email address to send test to (required)
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt send_test_email [email protected]" www-data
info

Shows detailed trace information. Actually sends email.

Email Digest Send​

Sends email digests to users with pending notifications. Typically run via cron.

Related:

  • passbolt email_digest preview - Preview digests without sending
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt email_digest send" www-data
info

Note: when the EmailDigest plugin is disabled, passbolt email_digest send is aliased to the sender command.

Purge Email Queue​

Removes successfully sent emails and failed emails retried 3+ times from the queue.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt purge_email_queue" www-data
info

No options needed. Does not remove emails still being retried.

Database Migrations​

Migration Status​

Shows which migrations have been applied and which are pending.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake migrations status" www-data

Migrate​

Runs pending database migrations. Automatically clears cache after migration (unless --no-clear-cache).

Options:

  • --backup - Create database backup before migration
  • --no-clear-cache - Don't clear cache after migration
  • --datasource - Specify datasource (default: default)
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt migrate" www-data

Examples:

# Safe migration with backup
./bin/cake passbolt migrate --backup

# Migration without cache clearing (advanced)
./bin/cake passbolt migrate --no-clear-cache

One-Time Post-Upgrade Commands​

These commands are run once, after a specific upgrade or operation, not on a schedule.

Backfill Secret History Data​

Two commands fill in data that new writes now record natively, for the secrets that already existed before the upgrade. Run them once, in this order, after upgrading an instance that already contains secrets to version 5.8.0 or later. They are not a prerequisite for enabling secret history, but without them the resources created before the upgrade have no starting revision.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt populate_secret_revisions_for_existing_secrets" www-data
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt populate_created_by_and_modified_by_in_secrets" www-data

Neither command takes any option, and both are safe to run again: they only touch the rows that are still empty, so a second run finds nothing to do and cannot create duplicates. On an instance created in 5.8.0 or later they have nothing to do at all.

No progress output

Each command prints one line when it starts and one when it finishes, with nothing in between and no count, so a large vault looks like a stalled terminal. A PHP execution timeout can also cut a very large backfill short: run it again, which is harmless. To check where you stand, count the rows that remain empty, for example SELECT COUNT(*) FROM secrets WHERE secret_revision_id IS NULL;.

The first command reconstructs who last modified each secret from the action log. On an instance whose action logs have been purged, that attribution falls back to the creator of the resource, without failing.

Re-Run the PostgreSQL Migrations​

Marks three schema migrations as not applied, the two that convert ASCII field encodings and the one that converts identifier fields to UUID, then runs the pending migrations again. Their implementation differs between MySQL or MariaDB and PostgreSQL, so this command exists to apply the PostgreSQL variants on an instance where they were recorded as done without having run.

Run it after importing a database into PostgreSQL, typically a conversion from MySQL where phinxlog came along with the data, or when passbolt support points you to it. It refuses to run on any driver other than PostgreSQL, reporting "This command is available with a Postgres connection only."

Options:

  • -d, --datasource - Datasource name, default or test (default: default)
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt migrate_postgres" www-data
warning

This command replays schema migrations on a database that holds data. It writes only to the migrations table itself, not to your application data, but the migrations it triggers do alter the schema. Take a database backup first and run it in a maintenance window, as you would for any migration.

info

Cannot rollback - use migrations rollback for that. Backup option uses sql_export.

Cache Management​

Cache Clear All​

Clears all application cache files. Run after updates.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake cache clear_all" www-data

Subscription Management​

Subscription Import​

Imports a subscription key file.

info

Enterprise Edition only.

Options:

  • -f, --file - Path to subscription key file
  • -t, --text - Subscription key as Base64 text
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt subscription_import" www-data

Examples:

# Import from file
./bin/cake passbolt subscription_import -f /path/to/subscription_key.txt

# Import from text (useful for automated deployments)
./bin/cake passbolt subscription_import -t "BASE64_ENCODED_KEY_HERE"
info

Either file or text required (not both). Key must be valid base64-encoded.

Subscription Check​

Verifies subscription status and validity.

info

Enterprise Edition only. Note: passbolt license_check is an alias for this command.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt subscription_check" www-data
info

passbolt license_check is an alias.

Edition Downgrade​

Downgrades a Pro Edition instance to the Community Edition. Available since passbolt 5.13.0.

danger

DESTRUCTIVE: This permanently wipes Pro data from the database. This cannot be undone!

Options:

  • -u, --username - Email of the administrator performing the downgrade (required). The action is attributed to this user in notification emails and audit trails.

Behaviour:

  • Asks for confirmation before downgrading (defaults to no)
  • Exits successfully if the instance is already on the Community Edition, so automation can re-run it safely
  • Refuses to run when the PASSBOLT_SECURITY_EDITION_DOWNGRADE_DISABLED environment variable is set to true
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt edition_downgrade --username [email protected]" www-data
info

The same downgrade is available from the Subscription page in the administration panel. See updating your subscription key.

Directory Synchronisation​

info

Enterprise Edition only. Requires LDAP PHP extension and LDAP integration configured in Passbolt.

Directory Sync​

Synchronises users and groups from LDAP/AD. Use --persist to save changes to the database.

Available commands:

  • directory_sync all - Synchronise both users and groups
  • directory_sync users - Synchronise users only
  • directory_sync groups - Synchronise groups only
  • directory_sync test - Test synchronisation without making changes (safe)
  • directory_sync debug - Debug configuration helper (safe)
  • directory_sync purge_directory_reports - Delete old synchronisation reports (irreversible, no dry-run)

Output format: Shows Created/Updated/Deleted sections for Users and Groups. Error messages include instructions for ignoring specific entries if needed.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake directory_sync all --persist" www-data

Examples:

# Test synchronisation (safe, no changes)
./bin/cake directory_sync test

# Debug configuration
./bin/cake directory_sync debug

# Synchronise users only
./bin/cake directory_sync users --persist
info

Cannot be run as root - must run as web server user. Error messages include instructions for ignoring entries. See Advanced Directory Options for sync error explanations. See LDAP Sync Cronjob for automated setup.

Purge Directory Reports​

Deletes old synchronisation reports and their entries from the database. Available since version 4.10.0.

Every synchronisation run writes a report, plus one item row for each directory entry it reports on, including the entries where nothing changed. A directory of a few thousand entries synchronised several times a day therefore adds tens of thousands of rows a day, and nothing prunes them: there is no retention setting, and none of the bundled cron scripts calls this command. On long-running instances these tables reach several gigabytes, so plan a periodic purge.

warning

This command has no dry-run and no batch size: it deletes as soon as it runs, with one delete per table. Take a database backup first, or at least count the rows you are about to remove. On a table that has already grown to several gigabytes, start with an old --before date and move it forward over successive runs rather than purging everything at once, as a single large delete can hold locks and inflate the transaction log.

Options:

  • -b, --before - Date in dd-mm-yyyy format, before which reports are purged (required). A date that does not match this format is rejected with "Invalid before date provided."

Only reports with a "done" status are purged, so a report still in progress is kept even when it predates the date. The counts can therefore be lower than you expect.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake directory_sync purge_directory_reports --before 01-01-2026" www-data

The command prints "No reports to purge." when nothing matches, otherwise the number of report entries and of report item entries it deleted.

info

Like the other directory_sync commands, this one cannot run as root and requires the LDAP integration to be configured and enabled. Mind the consequence: if you have disabled directory synchronisation but still carry a large reports table, you need to enable the integration again to run the purge.

User Management​

These commands act on user accounts from the server. They all refuse to run as root, so run them as the web server user. The Docker examples use docker-compose-ce.yaml, replace it with docker-compose-pro.yaml on the Pro Edition.

Mind the option names

recover_user takes --username, while mfa_user_settings_disable and user_promote_to_administrator take --user-username. All three accept the short form -u, which is what the examples use.

List Users​

Prints every registered user as a table, with the columns Role, Username, Last name, First name, Created At, Active, Disabled, Deleted and MFA enabled. It takes no options.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt users_index" www-data

Two differences with the users workspace are worth knowing: the listing includes deleted users, which is why there is a Deleted column, and the MFA enabled column is only meaningful when the MFA plugin is enabled, otherwise every row reads no. The output is an ASCII table with no JSON or CSV option, so treat it as a diagnostic tool rather than something to parse. When the instance has no user, it prints "This organization has no registered users."

Recover a User Account​

Prints a recovery URL for a user who can no longer sign in, which is the way out when nobody can send an invitation from the interface any more, typically a locked-out administrator.

Options:

  • -u, --username - The email address of the user (required)
  • -c, --create - Create a new recovery token
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt recover_user -u [email protected] -c" www-data

Drop the -c to print the URL of an existing, still valid token instead: without it, the command looks for an active recovery token and stops if there is none, suggesting the option. The user must exist, be active, meaning they completed their setup, and not be suspended, otherwise the command reports "The user does not exist or is not active or is disabled." A user who was invited but never completed their setup needs a new invitation instead.

warning

The URL contains an account recovery token, so treat it as a secret: send it over a channel you trust, and mind that it expires. And keep its scope in mind, it hands the user a way back into the recovery flow, not access to their data: they still need their private key and their passphrase to complete it. A lost passphrase is a different problem, covered by account recovery.

Disable MFA for a User​

Disables multi-factor authentication for one user, from the server. This is the CLI counterpart of the "Disable MFA" entry of the users workspace, for when the interface is not an option.

Options:

  • -u, --user-username - The email address of the user (required)
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt mfa_user_settings_disable -u [email protected]" www-data

On success it prints The MFA for user "<email>" has been disabled. The command also invalidates the verified MFA tokens of that user, so a device that was remembered for a month stops being trusted, and it triggers the notification email. See disable MFA for a specific user for the interface route.

note

If the user has no active provider, the command reports that MFA is already disabled. That message also appears when MFA is disabled for the whole organisation, so it does not prove that the user had no settings.

Promote a User to Administrator​

Grants the administrator role to a user. The command performs the change on behalf of an existing administrator, whose email address you pass as the second option.

Options:

  • -u, --user-username - The user to promote (required)
  • -a, --admin-username - The administrator to act on behalf of (required)
sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt user_promote_to_administrator -u [email protected] -a [email protected]" www-data

There is no confirmation prompt, and there is no reverse option: the command only promotes. To remove the administrator role, use the users workspace or the API.

Resource Management​

Notify About Expired Resources​

Sends email notifications to users about expired or expiring resources based on password expiry policies.

sudo su -s /bin/bash -c "/usr/share/php/passbolt/bin/cake passbolt notify_about_expired_resources" www-data
info

Requires password expiry policies to be configured. Typically run via cron.

Command Safety Reference​

Safe Commands (Read-Only)​

  • healthcheck
  • datacheck
  • show_logs_path
  • version
  • subscription_check / license_check
  • migrations status
  • users_index
  • directory_sync test
  • directory_sync debug
  • All commands with --dry-run option
  • All cache, routes, plugin list commands

Commands Requiring Caution (Modifying)​

  • cleanup (without --dry-run)
  • migrate
  • send_test_email
  • action_logs_purge (without --dry-run)
  • purge_email_queue
  • email_digest send
  • notify_about_expired_resources
  • recover_user (with --create, which issues a new recovery token)
  • populate_secret_revisions_for_existing_secrets and populate_created_by_and_modified_by_in_secrets - write data, but safe to run again
  • migrate_postgres - replays schema migrations
  • mfa_user_settings_disable
  • user_promote_to_administrator - grants the administrator role, with no confirmation and no reverse option
  • directory_sync purge_directory_reports - irreversible delete, with no --dry-run and no batching
  • directory_sync synchronisation commands (except test/debug), which run in dry-run mode unless --persist is passed

Destructive Commands (Cannot be Undone)​

  • truncate_account_recovery_tables - Deletes all account recovery data
  • edition_downgrade - Permanently wipes Pro data and switches the instance to the Community Edition
  • drop_tables - Drops ALL database tables (not documented here - use only in development)
warning

Always run commands with --dry-run when available, and make backups before running destructive or modifying commands.

Best Practices​

# Check help first
./bin/cake COMMAND --help

# Use dry-run when available
./bin/cake passbolt cleanup --dry-run
./bin/cake passbolt action_logs_purge -r 90 --dry-run

# Make backups before destructive operations
./bin/cake passbolt sql_export
./bin/cake passbolt migrate --backup

# Run healthcheck regularly
./bin/cake passbolt healthcheck --hide-pass

# Use status report for troubleshooting
./bin/status-report > diagnostic_report.txt

Additional Resources​