Configuration and files

Store selection

Orchard looks in this order for local-file commands:

1. --store <path> or -s <path>.
2. The OURCANA_STORE environment variable.
3. ourcana.json in the current directory.
4. A .our file in the current directory.
5. A platform app store file, if discoverable.

A missing explicit path or environment path is an error, not a reason to fall through. If several .our files exist, the directory iteration order decides; use --store to avoid relying on that order.

export OURCANA_STORE="$HOME/exports/ourcana.json"
or info
# Overrides the environment selection:
or --store ./another-system.our info

Identity, remote, entitlement and Online commands run before store discovery. They do not need a local store, and --store does not choose the identity used for a remote request.

Formats and app data

The readers support Ourcana flat JSON, version 3 graph JSON, .our/.zip archives and .willowdrop stores. JSON decoding also recognizes PluralKit and SimplyPlural export shapes. File extensions affect archive/drop selection; do not rename arbitrary files to force a format.

On macOS, app discovery checks the sandboxed container's Application Support directory, then the non-sandboxed one:

~/Library/Containers/com.ourcana.ourcana/Data/Library/Application Support/com.ourcana.ourcana/
~/Library/Application Support/com.ourcana.ourcana/

Under those roots it checks graphs/<namespace>/graph.willowdrop, then graph.json. It prefers the graph index's first usable entry and otherwise scans sorted graph directories. Older stores directly under the root are also considered. Use an explicit file for a particular system. Permission-denied errors may require a separate export or carefully chosen terminal Full Disk Access; do not grant access just to read an export you already have.

Linux and Windows app-directory discovery does not currently scan nested graph files. Use --store or OURCANA_STORE there rather than assuming it will locate the app's active graph.

Identity and remote files

The default directory is the platform's configuration directory with ourcana appended:

Set ORCHARD_CONFIG_DIR to use a different directory directly; Orchard does not append another ourcana component to it.

keys.json holds enrolled namespace/subspace records, secret seeds and the active identity selection. remote.json holds the endpoint, transport preference and any gate token, pairing delegation and E2E keys. They are not harmless dotfiles. Keep backups private, and do not commit or attach them to bug reports. On Unix, Orchard restricts these files to owner read/write permissions; the Windows implementation does not apply Unix modes.

Other environment settings

NO_COLOR disables rich normal output when present, even when its value is empty. OURCANA_STORE and ORCHARD_CONFIG_DIR are the Orchard-specific path overrides. Shell variables such as HOME, XDG_CONFIG_HOME and APPDATA also affect the platform directory library's defaults.

There is no configuration flag for choosing a different file containing CLI options. Use the documented global flags and or remote rather than inventing a config format.