CLI Reference

Trowel is the primary CLI for managing Orchard groves. All commands follow the pattern trowel <command> [subcommand] [flags].

Global Flags

Flag	Short	Description
`--server`	`-s`	Orchard server URL (overrides config and env var)
`--cultivator`		Cultivator ID (overrides config and env var)
`--target`	`-t`	Named config target to use (overrides the active target)
`--help`	`-h`	Show help
`--version`	`-V`	Show version

`trowel status`

Check the connection to the Orchard server:

code

trowel status

Grove Commands

`trowel grove plant`

Plant a new grove from a git repository:

code

trowel grove plant <repository-url> [flags]

Flag	Short	Description	Default
`--branch`	`-b`	Branch to check out	`main`
`--name`	`-n`	Grove name	(auto-generated)
`--machine`	`-m`	VM size: `small`, `medium`, `large`	`small`
`--spec`	`-s`	Environment spec: `auto`, `devcontainer`, `devfile`	`auto`

`trowel grove list`

List all groves (alias: ls):

code

trowel grove list [flags]

Flag	Short	Description
`--all`	`-a`	Include `CLEARED` groves

`trowel grove show`

Show details of a specific grove, including VM and container info:

code

trowel grove show <grove-id>

`trowel grove connect`

Connect to a grove via SSH (alias: ssh). The grove must be in FLOURISHING state:

code

trowel grove connect <grove-id>

`trowel grove clear`

Delete a grove:

code

trowel grove clear <grove-id> [flags]

Flag	Short	Description
`--force`	`-f`	Skip confirmation prompt

Config Commands

`trowel config init`

Create a default config file at ~/.orchard/config.toml, or migrate an existing config.properties to TOML:

code

trowel config init

`trowel config show`

Display current configuration and effective settings:

code

trowel config show

`trowel config set`

Update values on the active (or a named) target:

code

trowel config set --server http://orchard.example.com:7778
trowel config set --cultivator <your-uuid>
trowel config set --target staging --server https://staging.example.com

`trowel config target`

Manage named targets:

code

trowel config target list                 # list all targets (* marks the active one)
trowel config target add staging --server https://staging.example.com --cultivator <uuid>
trowel config target set staging           # switch the active target
trowel config target remove staging

See CLI Configuration for the full configuration model.

Dev Server Commands

These commands manage a local Orchard stack using native binaries cached under ~/.orchard/bin/. trowel dev-server start launches two processes:

orchard-server (the core API) on the core port — uses an embedded H2 database (~/.orchard/data/orchard), so PostgreSQL is not required.
orchard-ui-backend (the Canopy UI) on the UI port — serves the dashboard and reverse-proxies /api/** to the core. The binary is downloaded automatically from the orchard-ui releases and cached at ~/.orchard/bin/orchard-ui-backend.

In dev mode the UI auto-authenticates as the cultivator in your ~/.orchard/config.toml, so no extra setup is needed.

`trowel dev-server start`

Start the local dev server in the background:

code

trowel dev-server start [flags]

Flag	Short	Description	Default
`--port`	`-p`	UI (browser) port	`7777`
`--core-port`		Orchard core API port	`7778`
`--no-ui`		Start the core API only, without the Canopy UI	false
`--ui-version`		Pin a specific orchard-ui-backend release	latest
`--open`		Open the UI in your browser once it is ready	false
`--foreground`	`-f`	Run in foreground instead of background	false
`--verbose`	`-v`	Enable debug logging	false

Open http://localhost:7777 for the Canopy UI; the core API is reachable directly at http://localhost:7778. This core port matches the default server value written by trowel config init.

`trowel dev-server stop`

Stop the local dev server:

code

trowel dev-server stop

`trowel dev-server status`

Check the status of the local dev server:

code

trowel dev-server status

Your First Grove

Configuration