CLI Configuration

The Trowel CLI reads configuration from ~/.orchard/config.toml. Run trowel config init to create this file with defaults.

Configuration File

Configuration is organized into named targets, each describing a server to connect to. The active key selects which target is used when no target is specified.

code

# ~/.orchard/config.toml
active = "local"
 
[targets.local]
server = "http://localhost:7778"
cultivator = "<your-cultivator-uuid>"

Key	Description
`active`	Name of the target used when none is given on the command line
`[targets.<name>]`	A named target
`server`	URL of the Orchard API server
`cultivator`	Your cultivator UUID, used to identify you to the server

Authentication Keys

Running trowel login (see the CLI Reference) adds several more keys to the active target to store your Fence session. These are written and refreshed automatically — you shouldn't need to edit them by hand.

Key	Description
`fence_server`	The Fence server used to authenticate
`access_token`	OAuth2 access token sent with API requests
`refresh_token`	Used to silently refresh the access token when it expires
`expires_at`	Unix timestamp (seconds) when the access token expires

Legacy `config.properties`

Earlier versions used a flat ~/.orchard/config.properties file with a single server and cultivator:

code

server=http://localhost:7778
cultivator=<your-cultivator-uuid>

This format is still read when no config.toml exists — it loads as a single target named default. Run trowel config init to migrate it to TOML.

Managing Targets

Use trowel config set to update the active (or a named) target without editing the file directly:

code

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

Manage multiple targets with trowel config target:

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

Environment Variables

Environment variables take precedence over the config file:

Variable	Description
`ORCHARD_SERVER_URL`	Orchard server URL
`ORCHARD_CULTIVATOR_ID`	Your cultivator UUID
`ORCHARD_TARGET`	Named target to use (overrides the active target)

Global Flags

Individual commands can override configuration inline:

code

trowel --server http://other-server:7778 grove list
trowel --cultivator <uuid> grove plant https://github.com/your-org/repo
trowel --target staging grove list

Priority Order

Settings are resolved in this order (highest to lowest priority):

Command-line flags (--server, --cultivator)
Environment variables (ORCHARD_SERVER_URL, ORCHARD_CULTIVATOR_ID)
The active config target, or the target selected by --target / ORCHARD_TARGET
Default (http://localhost:7778)

Command Reference

Devcontainers