Browse the manual
CLI commands
Artisan commands for installing, updating, and maintaining Pepper.
On this page
For: developers and system administrators managing Pepper from the command line.
Pepper does not require CLI access for daily use. The web installer handles setup. These commands are for developers, hosting administrators, and troubleshooting.
Installation and setup
| Command | Description |
|---|---|
php artisan migrate |
Run forward database migrations |
php artisan migrate:rollback |
Refused before migration history or data changes; restore matching code and a verified backup |
php artisan migrate:reset |
Refused before migration history or data changes; restore matching code and a verified backup |
php artisan db:seed --class=DemoSeeder |
Unavailable; choose sample content during fresh web installation |
php artisan demo:reset |
Unavailable, including with --force; leaves existing data unchanged |
To explore sample content, create a separate disposable installation and enable Add demo data in the web installer. Your owner account owns the sample business records. Samples also include four fictional staff collaborators and one guest, with generated profile photos and discarded random passwords. Setup sends no invitations or email. See sample content during installation.
Disposable demo rebuild
demo:rebuild creates or rebuilds a separate disposable demo from a deployment script. It does not run the web installer.
Use a separate disposable database on MySQL 8.4. Keep APP_URL set to your demo's address. The command accepts any address and requires no extra URL setting. A first deployment can create the demo through the command; you do not need to open the web installer.
Rebuilding deletes all business records in the configured database. It keeps existing login credentials and supported roles, and it adds each missing demo person. The encrypted recovery snapshot holds logins, not business records. Use this command only for a disposable demo.
- Set
DEMO_MODE=true,APP_IS_INSTALLED=trueandMAIL_MAILER=login the demo's environment file. - Keep the existing
APP_KEYand database connection. - Stop and drain the demo's cron jobs and queue workers.
- Keep storage shared across releases.
- Run these commands in the demo's application directory:
php artisan config:clear
php artisan down
php artisan demo:rebuild --force
php artisan cache:clear
php artisan optimize
php artisan storage:link
The command requires demo mode, installed state, maintenance and --force. It checks the live database version before any writes. MariaDB and MySQL versions other than 8.4 refuse. For an empty database, add --initialize to create the demo accounts and samples.
Existing accounts need credentials and the owner, admin, accountant or employee role, or one of the demo roles Sales, Project lead or Front desk. The demo must have one active owner. Any other custom role refuses before the rebuild. Rebuilding creates new account IDs to invalidate old sessions. Old uploaded files remain in shared storage.
If all commands succeed, activate the new release. Run php artisan up. Resume cron jobs and queue workers. Check each existing login and the sample invoices.
First Forge installation
Use your dedicated empty MySQL 8.4 database. Set DEMO_MODE=true and APP_IS_INSTALLED=true in Forge. Keep your current APP_KEY and database settings. The command creates the tables and samples without changing the environment file or key. It uses an array mailer during setup, so your configured mail provider receives no messages.
Use this deployment script once:
set -eu
$CREATE_RELEASE()
cd "$FORGE_RELEASE_DIRECTORY"
composer dump-autoload --optimize --no-scripts --no-plugins --no-interaction
$FORGE_PHP artisan config:clear
$FORGE_PHP artisan down
$FORGE_PHP artisan demo:rebuild --initialize --force
$FORGE_PHP artisan cache:clear
$FORGE_PHP artisan optimize
$FORGE_PHP artisan storage:link
$ACTIVATE_RELEASE()
$RESTART_QUEUES()
$FORGE_PHP artisan up
Demo people
The sign-in page of a demo starts with the people of Pulse Studio in three groups: Your team, Your clients and Their customers. Click a person to sign in as that person. No password is needed, and changes are not saved. Any person can connect their own AI to act for them, with the same permissions and approvals, so the demo has no separate AI person. The email form stays available under Sign in with email and password. Each account signs in there with its email and the password welcome3210.
| Person | Role | What the person does | |
|---|---|---|---|
| Mara Jansen | admin@example.com |
Owner | Sees and changes everything |
| Anna Becker | manager@example.com |
Admin | Manages people, settings and all work |
| Leo Martin | accountant@example.com |
Accountant | Reads invoices, purchases and reports |
| Sofie Brandt | sales@example.com |
Sales | Works leads and deals, and sends quotes |
| Jun Okada | projects@example.com |
Project lead | Plans projects, tasks and the team's time |
| Lina Vermeer | frontdesk@example.com |
Front desk | Takes bookings and serves customers at the counter |
| Noah Williams | user@example.com |
Employee | Works on projects and invoices own work |
| Sam Rivera | guest@example.com |
Guest with the Employee role | Sees only the Client work board |
Sign in as Mara and open Assistant to see how a client project starts in a chat. The panel shows a replay of the conversation in which Mara and Eva of Portside set up the spring print fair: the quote, a project, its board and a draft landing page. Each of these records shows You created this with the Assistant with Open conversation. The replay makes no AI calls and has no message field. Only Mara sees it.
Your clients also shows the Canal Coffee client account. Femke Dekker owns that account and runs its own website, shop, bookings and stamp card. The studio built the Canal Coffee website for her with an edit grant she can see, and Femke publishes it. Her shop sells beans, a mug and a barista morning as Canal Coffee B.V., with its own invoice numbers and a Stripe test account. Esmee Meijer works there. She packs web orders, receives stock and stamps cards at the counter. Both sign in with welcome3210 and land in the client account, not in the studio's workspace. Femke lands on the account overview, and Esmee lands on Scan:
| Person | Client account | Role | |
|---|---|---|---|
| Femke Dekker | femke@canal-coffee.example.test |
Canal Coffee | Owner |
| Esmee Meijer | esmee@canal-coffee.example.test |
Canal Coffee | Counter staff |
Their customers shows Sanne de Graaf, who has a customer account on the Portside Print Fair website and bought prints there. Click the card, then click Continue as Sanne de Graaf to open that website's account page as Sanne, with her orders and downloads. A customer account has no password; outside the demo it signs in with an email code. In the demo, the account page refuses every change and shows Demo mode is read-only. Changes are not saved.
Sales, Project lead and Front desk are custom roles. The demo builds them from existing permissions only. Owners and admins can read their permissions under Roles.
The sign-in page shows a person only while the account is active and keeps its role. One-click sign-in also needs the public password. If you change a demo password, one-click sign-in refuses that person; sign in with the email form instead. One-click sign-in exists only when DEMO_MODE=true.
Initialization creates all eight team and guest accounts. The sample story creates Femke and Esmee on every rebuild, as it creates Rosa and Mats; a rebuild never preserves them as logins. A normal rebuild keeps every existing login unchanged. It adds each demo person that has no account, so an older demo gets the new people at its next rebuild. It never adds a second owner. Other fictional colleagues, such as Rosa Teixeira and the former intern Mats de Boer, have discarded random passwords. Each rebuild creates them again. All eleven people on the demo sign-in page have portraits. Team, guest and client users receive the same photos in their seeded profiles. Rebuilds preserve the guest restriction and existing passwords, and date the sample history from the rebuild day.
The dedicated demo adds Open House, a neighbourhood of three active customer businesses: Canal Coffee on Venue, Harbour Homes on Listings and Northwind Studio on Showcase. Each has published widgets, named placements, recent activity, visitor records, a team and paid and unpaid service invoices. Open an account to follow a customer from its website into the business's records. Rebuilds move the examples with the current date. These active customer examples are exclusive to dedicated demo setup; fresh buyer samples stay closed.
Websites includes published Pulse Studio and Canal Coffee sites, plus a private Portside Print Fair site. Pulse Studio has English and Dutch pages, connected services and an inquiry form. Its later draft leaves the published pages unchanged, so History shows both states. The examples use bundled photographs and the existing form, menu and booking widgets.
Initialization checks only the configured database and refuses any existing table or view there. A matching encrypted snapshot permits retry of its own interrupted setup. It does not adopt an unknown partial installation. Keep cron jobs and queue workers stopped during deployment, and keep storage shared across releases.
After initialization succeeds, remove --initialize for later deployments. The normal rebuild keeps existing account passwords, including passwords you changed. You do not need to run the installer or copy an environment file back into Forge.
Forge deployment
Keep --no-plugins on the Composer command. --no-scripts skips scripts but still permits plugins to load.
Run the rebuild before activating the new release. Keep the normal dependency and frontend build stage. composer dump-autoload does not install dependencies or build assets.
set -eu
$CREATE_RELEASE()
cd "$FORGE_RELEASE_DIRECTORY"
composer dump-autoload --optimize --no-scripts --no-plugins --no-interaction
$FORGE_PHP artisan config:clear
$FORGE_PHP artisan down
$FORGE_PHP artisan demo:rebuild --force
$FORGE_PHP artisan cache:clear
$FORGE_PHP artisan optimize
$FORGE_PHP artisan storage:link
$ACTIVATE_RELEASE()
$RESTART_QUEUES()
$FORGE_PHP artisan up
Stop and drain cron jobs and queue workers before this script starts. Resume them after successful activation. Keep storage shared across releases.
Forge stops a deployment after 10 minutes. The rebuild must finish well inside that limit, together with the Composer and optimize steps. While the rebuild runs, the command shows each finished stage with its seconds and queries. At the end it shows the total, for example Demo rebuilt in 65 s. Check this value after each deployment. If a deployment stops at the time limit, the last stage line shows how far the rebuild got.
The rebuild creates the tables from a copy of the database structure that comes with the application. If that copy does not match the application's migrations, the rebuild runs all migrations, which takes longer. It then keeps an encrypted copy in storage/app/private/forge-demo for later rebuilds. Keep storage shared across releases so that this copy stays available.
The rebuild does not make the PDF originals of the issued sample documents. When cron jobs run again, outbox:process makes 20 originals each minute. If you open a PDF before then, the demo makes its original at once.
Failed rebuild
A refusal or failure returns a nonzero exit code. Configuration refusals explain the missing condition. Database failures show the stage, SQLSTATE and driver error code. Unexpected failures also show the stage and exception type. Errors include the PHP source file and line when the source belongs to the application or its dependencies. Other source locations show unavailable. They do not print SQL, connection details, absolute server paths or account values.
If the command reports APP_IS_INSTALLED must be true, set APP_IS_INSTALLED=true in the demo environment. Run php artisan config:clear and retry. For a first deployment to an empty database, use --initialize --force.
If a login table is missing, the command names users, roles or model_has_roles. Verify that the release uses the existing demo database. For a new empty demo, use the first-deployment script above. Do not create empty login tables to bypass the check. An encrypted recovery snapshot allows a retry after an interrupted rebuild even if those tables are absent.
Keep maintenance active. Do not activate the new release. Keep storage/app/private/forge-demo/accounts.enc or initialize-accounts.enc if it exists. Keep the same APP_KEY, database connection and shared storage. Correct the reported condition, then rerun the same command. Retain --initialize when you retry an interrupted initialization. Initialization and normal rebuild share a lock and refuse while the other operation has a pending snapshot.
If failure occurs after table replacement, the previous business records are gone. Activating old code does not restore them. The retry recreates the demo's tables and views, even if the migration history table is missing. It restores logins from the encrypted snapshot and creates new samples. The operation stays within the configured database. Success removes that snapshot and leaves maintenance active.
Cache management
| Command | Description |
|---|---|
php artisan config:cache |
Cache configuration (recommended for production) |
php artisan config:clear |
Clear configuration cache |
php artisan route:cache |
Cache routes (recommended for production) |
php artisan route:clear |
Clear route cache |
php artisan view:cache |
Cache compiled Blade views |
php artisan view:clear |
Clear compiled Blade views |
php artisan cache:clear |
Clear application cache |
Maintenance
| Command | Description |
|---|---|
php artisan down |
Put the application in maintenance mode |
php artisan up |
Bring the application back online |
php artisan storage:link |
Create the public storage symlink |
For replacement recovery, run storage:link after down and before recovery:restore. It links public/storage to that replacement's storage/app/public.
Keep the storage directories as real directories. Follow the backup recovery steps or replacement update procedure.
Automation
These commands run automatically when you configure a cron job. You can also run them from the command line.
| Command | Description | Schedule |
|---|---|---|
php artisan outbox:process |
Send queued emails, retry temporary failures, and store missing issued originals | Every minute |
php artisan recurring:generate |
Generate invoices for all active recurring schedules that are due | Daily at 06:00 in the business timezone |
php artisan reminders:send |
Queue scheduled payment reminders for overdue and upcoming-due invoices | Daily at 07:00 in the business timezone |
php artisan backup:create |
Create a database and media backup | Daily or weekly (configurable in Settings) |
php artisan events:deliver |
Catch up record events and inbox notifications | Every minute |
php artisan calendar:process |
Process Calendar invitations and due inbox reminders | Every minute when Calendar is available |
php artisan automations:process |
Admit due schedules, derive event work, continue runs and process eligible signed webhook attempts | Every minute when Automations is available |
php artisan assistant:prune |
Remove expired local conversation and operational card bytes; keep business records, charged usage and started-action facts | Hourly; makes no provider request |
php artisan inbox:push |
Retry eligible mention and assignment push notifications | Every minute |
php artisan inbox:digest |
Send selected unread notifications once per local day, at or after 08:00 | Hourly |
php artisan boards:due |
Add due-card reminders for assigned people | Hourly |
php artisan backup:clean |
Remove backups exceeding the retention limit | Not scheduled; creating a backup applies retention |
Recurring invoice generation runs first (06:00), then reminders (07:00), so Pepper can check the new invoices when evaluating reminders.
Each recurring:generate run produces at most one invoice per schedule. If the server missed multiple days, subsequent runs catch up one invoice at a time.
The email outbox
Document emails, reminders and auto-sent recurring invoices go through an outbox in the database. outbox:process needs no queue worker. Each run does this:
- It marks an attempt that has been busy for more than 10 minutes as Email result unknown.
- It tries up to 50 emails that are due, oldest first.
- It stores up to 20 missing issued originals.
The command prints the number of attempts and stored originals. If an email waits more than 15 minutes past its time, the document page says "The scheduler has not run since {time}. Check the cron job." Set up email delivery explains the retries.
Backups
These commands are optional. For full export and import without a shell, follow the browser backup guide.
Create a backup
php artisan backup:create
Creates a portable full database and media backup in storage/backups/. After success, it applies the configured retention limit.
| Option | Description |
|---|---|
--encrypted |
Ask for a passphrase at a hidden prompt. Use at least 6 characters |
--sealed |
Mark a final snapshot. Requires maintenance mode and --confirm-drained |
--confirm-drained |
Confirm that HTTP requests, cron and queue workers have stopped and drained |
--passphrase=SECRET |
Existing script option. Its value can appear in process arguments; prefer the hidden prompt |
php artisan backup:create --encrypted
A sealed backup records your confirmation. It cannot independently prove that the host stopped all writers.
Recover or verify
Run CLI recovery in a separate directory with the original APP_KEY and an empty database. Format-3 exports move between supported SQLite, MySQL and MariaDB engines. Older-to-newer recovery requires the target release to support the backup’s starting version. Format-2 SQL archives require their original database family. Keep the replacement in maintenance mode.
| Command | Purpose |
|---|---|
php artisan recovery:restore /secure/backup.zip |
Restore an authenticated same-version backup into empty storage and database |
php artisan recovery:restore /secure/backup.zip --encrypted |
Ask for the archive passphrase at a hidden prompt |
php artisan recovery:restore /secure/backup.zip --upgrade |
For supported older portable or SQL backups: check the starting version, restore its source schema, then apply target updates |
php artisan recovery:verify |
Recheck all records, references, counters, files, originals, key and target version before activation |
php artisan release:verify /secure/release.zip |
Check release file integrity and runtime compatibility against the manifest |
You can combine --encrypted and --upgrade for either format. Failed checks return a nonzero exit code. No recovery command exits maintenance or switches traffic.
Follow Backups for the complete recovery procedure and Updating for supported upgrades.
Clean old backups
php artisan backup:clean
Removes backups that exceed the retention limit. The command reads the retention count from Settings > Backups (default: 5) and keeps only the N most recent backups.
Options:
| Option | Description |
|---|---|
--keep=N |
Override the retention count from settings. Accepts 1 to 100. |
Example:
# Keep only the 3 most recent backups
php artisan backup:clean --keep=3
Cron setup
Pepper uses Laravel's task scheduler. Add this cron entry to your server:
* * * * * cd /path-to-made-with-pepper && php artisan schedule:run >> /dev/null 2>&1
Replace /path-to-made-with-pepper with the absolute path to your Pepper installation.
cPanel: Go to Cron Jobs, set the interval to "Once Per Minute (* * * * *)", and enter the command above.
Plesk: Go to Scheduled Tasks, add a new task with the command above, and set the schedule to every minute.
VPS / dedicated: Add the cron entry via crontab -e for the web server user (e.g. www-data).
Without cron, recurring invoices, automatic reminders, card due reminders and scheduled backups do not run. Queued emails, daily inbox digests and push retries wait. Automation runs, webhook retries and Calendar reminders also wait. Manual browser export and import still work. You can also run commands yourself.
Settings > Backups shows the last observed scheduler run. No observation means no run has reported; a report older than 5 minutes is overdue. This checks actual execution, not the host’s crontab. The page also shows the last backup result.
Queue
Scheduled tasks and document emails run without a queue worker. The outbox:process command sends document emails and reminders. User invitations send during the request after saving the invitation. You do not need queue:work or a QUEUE_CONNECTION change for these features.
Database
| Command | Description |
|---|---|
php artisan migrate:status |
Check migration status |
Do not use migrate:rollback or destructive database commands to recover an interrupted web installation. Fix the reported problem and retry the installer with the same database details. If installation stopped while it created the database tables, follow Failure recovery. Remove partial tables only from the new, empty target created by that failed attempt. Never remove existing business data. If Pepper refuses the partial target, create a new empty database or contact support with the setup reference.
Production optimization
Run these after deploying or updating Pepper:
php artisan config:cache
php artisan route:cache
php artisan view:cache
Related pages
Need help with the product?
Contact support