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

`trowel login`

Authenticate with Fence, Orchard's OAuth2 authorization server, using the OAuth 2.0 device authorization grant:

code

trowel login [flags]

Flag	Description	Default
`--fence-server`	Fence server URL	`$FENCE_SERVER_URL` or `https://fence.orchard.dev`
`--no-browser`	Don't attempt to open a browser automatically	false

trowel login requests a device code from Fence, prints a verification URL and short code, and opens your browser to it (unless --no-browser is set). Once you approve the request in the browser, Trowel polls Fence for the resulting access and refresh tokens and writes them to the active target in ~/.orchard/config.toml. Subsequent commands send the access token automatically.

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 stop`

Stop a grove, tearing down its containers and VM and transitioning it to DORMANT:

code

trowel grove stop <grove-id>

`trowel grove start`

Start a DORMANT grove, re-provisioning its VM and containers:

code

trowel grove start <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>

This connects directly to the seedling's SSH port, which suits local and dev setups. In production, connect through the SSH gateway instead.

`trowel grove clear`

Delete a grove:

code

trowel grove clear <grove-id> [flags]

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

Bee Commands

Bees are AI coding assistant processes attached to a grove. All bee commands take --grove/-g (or the ORCHARD_GROVE_ID environment variable) to identify the target grove.

The bee type is a free-form field on the API and CLI, but only opencode has a working adapter today. Installing any other type (claude-code, gemini, codex, kiro, custom) will fail — those names are reserved for future adapters, not currently-supported agents.

`trowel bee install`

Install a new bee in a grove (alias: add). The grove must be FLOURISHING:

code

trowel bee install <type> --grove <grove-id> [flags]

Flag	Short	Description
`--version`	`-v`	Version string (e.g., `latest`, `1.2.3`)

`trowel bee list`

List all bees in a grove (alias: ls):

code

trowel bee list --grove <grove-id>

`trowel bee show`

Show details of a specific bee:

code

trowel bee show <bee-id> --grove <grove-id>

`trowel bee wake`

Wake a HIBERNATING bee, restarting its agent process:

code

trowel bee wake <bee-id> --grove <grove-id>

`trowel bee smoke`

Shut down a bee:

code

trowel bee smoke <bee-id> --grove <grove-id>

`trowel bee status`

Show a summary of bee counts by state for a grove:

code

trowel bee status --grove <grove-id>

SSH Key Commands

Manage the SSH public keys registered to your account (alias: sshkeys). The SSH gateway accepts any registered key when you connect to one of your groves:

code

ssh -i ~/.orchard/keys/default -p 2222 <grove-id>@<gateway-host>

The SSH username is the grove ID. The grove's seedling must be running.

`trowel ssh-key add`

Generate a local ed25519 keypair (if one doesn't already exist) and register its public key:

code

trowel ssh-key add [flags]

Flag	Short	Description	Default
`--name`	`-n`	Key name	`default`
`--path`	`-p`	Register an existing public key file instead of generating one	—

Generated keys are stored under ~/.orchard/keys/<name> (private) and ~/.orchard/keys/<name>.pub. ssh doesn't look there by default, so pass the key with -i. If you registered your own key with --path, use its matching private key instead.

`trowel ssh-key list`

List registered keys with their IDs and fingerprints (alias: ls):

code

trowel ssh-key list

`trowel ssh-key remove`

Remove a registered key by ID (alias: rm):

code

trowel ssh-key remove <key-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/. By default, trowel dev-server start launches four processes:

fence (the Fence auth server) on the fence port — issues and validates OAuth2 tokens for the core API. Skip it with --no-auth to run without authentication, as in earlier versions.
orchard-server (the core API) on the core port — uses an embedded H2 database (~/.orchard/data/orchard), so PostgreSQL is not required. When Fence is running, the core is configured to validate its tokens (--spring.security.oauth2.resourceserver.jwt.issuer-uri).
orchard gateway (the SSH gateway) on the gateway SSH port — relays ssh <grove-id>@localhost sessions to seedlings using registered keys. It starts once the core is healthy and needs Fence, so --no-auth skips it too. Skip it on its own with --no-gateway. Its admin/health endpoint listens on port 8081. Unlike the UI binary, the Fence and gateway JARs aren't downloaded automatically. Download fence.jar and gateway.jar from the latest orchard release into ~/.orchard/bin/. Otherwise start exits and prints instructions for building them from source.
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.

The Canopy UI doesn't have its own Fence login flow yet, so it can't authenticate against the default Fence-enabled dev server. Start with --no-auth for local UI development until UI login support lands.

`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`
`--fence-port`		Fence auth server port	`7779`
`--no-auth`		Start without the Fence auth server (disables OAuth2); also skips the gateway	false
`--gateway-ssh-port`		SSH gateway port	`2222`
`--no-gateway`		Start without the SSH gateway	false
`--no-ui`		Start the core API only, without the Canopy UI	false
`--ui-version`		Pin a specific orchard-ui-backend release	`0.2.0`
`--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