Commands

Harbour commands describe workspace operations rather than branding. Human output is concise; automation can request stable JSON.

`workspace:install`

php artisan workspace:install

Purpose: interactively select the project's infrastructure and perform the one-time, non-destructive scaffolding required before Harbour can be used consistently across worktrees. Existing configuration and scripts are preserved.

With no options, a TUI first asks whether to auto-detect the existing project or choose components manually. Manual mode uses single-select controls for the database, cache, and mail transport, and a multi-select control for additional services. When service processes are needed it can generate Docker Compose, and it can set up the first workspace immediately.

Use --detect to accept the discovered Sail, Compose, Herd, and Laravel configuration without interaction.

For deterministic automation:

php artisan workspace:install \
    --detect \
    -d postgresql \
    -c redis \
    -m mailpit \
    --with=meilisearch,minio \
    --compose \
    --start \
    --no-interaction

Options:

Option	Choices	Purpose
`--detect`	—	Infer choices and host ports from Sail, Compose, Herd, `.env`, and `.env.example`. Explicit category flags override the inferred category.
`-d`, `--database`	`none`, `sqlite`, `mysql`, `mariadb`, `pgsql`, `mongodb`	Select the primary datastore. `postgres` and `postgresql` alias `pgsql`.
`-c`, `--cache`	`none`, `file`, `database`, `redis`, `valkey`, `memcached`	Configure cache plus safe session/queue defaults.
`-m`, `--mail`	`none`, `log`, `mailpit`	Configure local mail delivery.
`--with`	Comma-separated Sail service names or `none`	Add search, object storage, RabbitMQ, Selenium, Soketi, or express the entire selection with Sail vocabulary.
`--provider`	`shared`, `compose`	Use existing host/shared services or generate a workspace-specific Compose stack.
`--compose`	—	Shorthand for `--provider=compose`. Generates `docker-compose.harbour.yml`.
`--start`	—	Run `workspace:setup` after files are installed and wait for managed services to become ready.
`--json`	—	Return the selected stack, discovery sources, and file changes using the stable JSON envelope. Use `--detect` or explicit selections.

The full Sail-compatible service list is mysql, pgsql, mariadb, mongodb, redis, valkey, memcached, meilisearch, typesense, minio, rustfs, mailpit, rabbitmq, selenium, and soketi.

Conflicting choices—such as --database=sqlite --with=mysql or --with=redis,valkey—fail before project files are written.

--compose and --provider=shared conflict deliberately. Compose mode also requires at least one service-backed component; a SQLite/file/log selection has nothing to containerize. Starting is a normal Harbour setup operation, so all port, ownership, state, and teardown guarantees still apply.

`workspace:setup`

composer workspace:setup
php artisan workspace:setup --json

Purpose: make the current checkout usable. Setup allocates ports, creates the workspace database, renders .env, starts configured Docker/Compose dependencies, and runs migrations.

--fresh first tears down only resources proven to belong to this workspace, then builds them again. Add --force to suppress the confirmation prompt.

`workspace:status`

composer workspace:status
php artisan workspace:status --json

Purpose: inspect persisted workspace state quickly without scanning the machine or discovering unrelated Docker resources.

`workspace:env`

php artisan workspace:env
php artisan workspace:env --format=json
php artisan workspace:env --format=dotenv
php artisan workspace:env --format=shell

Purpose: expose resolved non-secret workspace variables to humans or external process launchers.

For example:

eval "$(php artisan workspace:env --format=shell)"
php artisan serve --port="$APP_PORT"

Secret values are omitted unless an output mode explicitly allows --show-secrets. Table and debug output always redact them.

`workspace:render`

php artisan workspace:render

Purpose: render .env.harbour into .env again using the existing workspace allocations. Use it after intentionally changing the template; it does not recreate the workspace.

`workspace:debug`

php artisan workspace:debug
php artisan workspace:debug APP_PORT
php artisan workspace:debug --json

Purpose: explain variable values, provenance, persistence, and secret classification. This is the first command to use when a rendered setting is surprising.

`workspace:teardown`

composer workspace:teardown -- --force

Purpose: remove this checkout's Harbour-owned resources, release its ports, restore its previous .env, and delete its state file.

The Composer -- forwards --force to Artisan. Force means “do not prompt,” never “ignore safety.”