From c58befca21b099fc52e3c8d3458209dc2823f878 Mon Sep 17 00:00:00 2001 From: Aly Raffauf Date: Mon, 3 Aug 2026 08:08:22 -0400 Subject: [PATCH] Document appa config and tighten README --- README.md | 91 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 9487175..329fa2a 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,9 @@ device, member, peer, node, and capability terminology. ## Run Appa as a service -After installation, Appa normally runs as one long-lived local daemon. It owns -the Iroh node, SQLite state, file watchers, and background synchronization. -The CLI and COSMIC app ask that one process to do their work. They do not start -another synchronizer for every command. +After installation, Appa runs as one long-lived local daemon that owns the +iroh node, local state, file watchers, and sync loop. The CLI and COSMIC app +connect to it as clients. Install the per-user service once @@ -31,7 +30,8 @@ foreground appa daemon serve ``` -`appa run` remains a foreground alias for the daemon. Stop either foreground +`appa run` is also a foreground daemon. Pass a folder to sync only that +folder; `appa daemon serve` always syncs every registered folder. Stop either form with Ctrl-C. ## What is different @@ -77,8 +77,8 @@ appa init ~/notes appa invite ~/notes --copy ``` -Send the invitation to your other device. It is reusable for 24 hours, so -treat it like a password. +Send the invitation to your other device. It is reusable for 24 hours with no +use limit, so treat it like a password. On the other device @@ -97,25 +97,24 @@ appa peers ~/notes appa members ~/notes ``` -Run `appa status --watch` for a live view. Pass a folder to `appa run` to sync -only that folder. +Run `appa status --watch` for a live view. ## Common commands -| Task | Command | -| --------------------- | ---------------------------------- | -| Add a folder | `appa init ` | -| Invite a device | `appa invite --copy` | -| Join a folder | `appa join --stdin` | +| Task | Command | +| ---------------------------- | ---------------------------------- | +| Add a folder | `appa init ` | +| Invite a device | `appa invite --copy` | +| Join a folder | `appa join --stdin` | | Run the daemon in foreground | `appa daemon serve` | -| Check sync health | `appa status [folder]` | -| List devices | `appa members ` | -| List peer routes | `appa peers ` | -| List conflicts | `appa conflicts ` | -| Show revision history | `appa history ` | -| Restore a revision | `appa restore ` | -| Stop syncing a folder | `appa leave ` | -| Remove a device | `appa revoke ` | +| Check sync health | `appa status [folder]` | +| List devices | `appa members ` | +| List peer routes | `appa peers ` | +| List conflicts | `appa conflicts ` | +| Show revision history | `appa history ` | +| Restore a revision | `appa restore ` | +| Stop syncing a folder | `appa leave ` | +| Remove a device | `appa revoke ` | `status`, `peers`, and `doctor` support `--json`. Run `appa --help` for every option. @@ -131,15 +130,47 @@ private/ .DS_Store ``` -Appa skips symbolic links. Non-Unicode filenames are rejected rather than -lossily renamed during synchronization. +Symbolic links are ignored: they are not synced and produce no error. +Non-Unicode filenames are rejected rather than lossily renamed during +synchronization. + +## Configure folders declaratively + +`appa config` registers folders from a TOML file instead of one command at a +time. It is useful for provisioning, backups, or version-controlling your +setup. The commands write to local state directly, so stop the daemon first +and pass `--offline`. + +Write a template from your current folders + +```sh +appa --offline config init +``` + +This writes `appa.toml` (the default path) with one `[[folders]]` entry per +folder. Each entry has a `path` and optional `name`, `folder_id`, +`capability_env`, and `mode`. Joined folders must set both `folder_id` and +`capability_env`. Keep capability secrets in the named environment variable, +not in the file. `mode` is `send_receive` (the default), `send_only`, or +`receive_only`. + +Validate, preview, and apply + +```sh +appa --offline config check +appa --offline config audit +appa --offline config apply +``` + +`apply` registers new folders and updates the mode of existing ones. Start the +daemon afterward; it picks up registered folders within a second. ## Change folders while Appa runs -The daemon refreshes its folder list and settings every second. You can run -`appa init`, `appa join`, `appa leave`, or apply configuration from another -terminal; it starts watching added folders, stops watching removed folders, and -reloads changed folder settings without a daemon restart. +The daemon refreshes its folder list and settings every second. Run `appa +init`, `appa join`, or `appa leave` from another terminal and it starts +watching added folders, stops watching removed folders, and reloads changed +folder settings without a daemon restart. ## Handle conflicts @@ -224,7 +255,7 @@ developing, or install the user service from the GUI nix develop -c cargo run -- daemon serve ``` -Build the packaged application with `nix build --impure .#appa-cosmic`. +Build the packaged application with `nix build .#appa-cosmic`. ## Troubleshoot @@ -238,7 +269,7 @@ checks identities, folders, manifests, membership, and recorded sync failures. Useful environment variables -- `APPA_HOME` sets the directory for Appa's identity and local state. +- `APPA_HOME` sets the directory for Appa's identity and local state. It defaults to `~/.local/share/Appa` on Linux, `~/Library/Application Support/Appa` on macOS, and `%LOCALAPPDATA%\Appa` on Windows. - `APPA_HISTORY_REVISIONS` sets the number of saved folder revisions. - `RUST_LOG=appa=debug` enables detailed logs. -- 2.51.2