festival installs, updates, and launches the Festival CLI suite (camp and
fest) and their plugins, pulling packages from a signed marketplace. Bare
festival opens a terminal hub; the same binary answers to CLI
subcommands for scripts and agents.
All your work, where you can find it.
Suite and Obey installs/updates configure terminal integration for the detected
login shell. Festival App uses this same installer contract during first run
and later repair. Open a new terminal after setup: cgo/fgo navigation and
ordinary interactive grok, claude, and codex launches work without copying
configuration lines. Obey wrapping supports Bash, Zsh and Fish on Linux/macOS,
including Linux Ghostty. PowerShell receives camp/fest helpers; Windows PTY
wrapping is not supported.
festival setup integrations # configure or repair
festival setup integrations --check --json # inspect readiness
festival setup integrations --disable # remember an advanced opt-out
festival setup integrations --enable # enable it againThe installer preserves unrelated shell content and custom provider launchers, backs up changed startup files, and reports conflicts or unsupported shells. Existing shells and provider sessions must be reopened/relaunched. Binary installation can succeed while integration needs attention; inspect the report or retry setup. See automatic setup for the API, installation ownership, prerequisites, and removal behavior.
These recordings predate the compact home redesign. The tapes use the current shortcuts; the GIFs retain the earlier appearance. Current PR evidence records the new home and Obey screen from the real binary.
Recorded against a real ./bin/festival binary (VHS + PTY).
First run: the setup card, the getting started tour, PATH with your consent
Home: boot splash, ambient flame, multi-activity booths, menu → doctor
Channels: install channel picker, shell/PATH, installed list
Community: run festival, select Join our Discord, and open the invite
Record with just vhs record docs/demos/festival-discord.tape on a desktop
with a browser. This tape opens the real invite using open on macOS or
xdg-open on Linux; VHS captures the terminal portion of the handoff.
Launchpad: open camp as a child tool, quit back to the hub
Reproduce locally:
just build
just vhs all # requires vhs, ttyd, ffmpegnpm / pnpm / bun:
npm install -g @obedience-corp/festivalmacOS:
brew install --cask Obedience-Corp/tap/festivalArch Linux:
yay -S festival-binShell script (macOS and Linux):
curl -fsSL https://raw.githubusercontent.com/Obedience-Corp/festival/main/install.sh | bashEach of these installs the whole suite (camp, fest, and festival), not
just this binary; they mirror the festival distribution repo's
README. Suite releases
that predate the hub install camp and fest only; the first release that
ships all three is the one that adds festival to every method above.
Festival Installer lives at github.com/Obedience-Corp/festival-installer;
its public command name is festival. CI tests the supported Linux and
macOS targets on amd64 and arm64. Tags matching v* publish portable
binaries and checksums through GitHub Releases. Until the first tag is
published, build it from source.
The marketplace document (obey-marketplace.json), the package index
(index.json), and every package manifest are signed with an Ed25519 key, id
obedience-marketplace-2026-01, whose public half is compiled into the
binary (internal/verify/trust.go). festival reads and enforces
obey-marketplace.json and package manifests; index.json is signed for
integrity and future use but is not read by festival today. By default
festival refuses to install or update anything whose metadata it cannot
verify against that pinned key.
To proceed anyway with unsigned development content, pass
--allow-unverified on the CLI (it prints a loud warning to stderr) or
accept the equivalent explicit consent prompt the TUI shows when it refuses
unsigned content. Artifact downloads are HTTPS-only, git remotes are
restricted to HTTPS, SSH, and local paths, and archive extraction is bounded.
Run festival doctor to check the trust state of every registered source in
one command; see SECURITY.md for what signing does and does not cover.
just build # → bin/festival
./bin/festival # opens the TUI on a terminalThe TUI home screen lets you:
- Open Camp and Fest, with the installed suite version visible
- View suite ownership and check for updates; install only when the suite is missing
- Open Obey agent sessions to install
obey+obor check for updates - List installed packages
- Browse the catalog and install plugins
- Uninstall receipt-owned packages
- Manage marketplaces
- Run doctor and PATH / shell-init guidance
- Join our Discord: open the Obedience Corp invite in your browser for help and project discussions. If no browser is available, the TUI shows the invite to open manually.
- Launchpad: open camp/fest tools (
camp wi,fest watch, …) as real subprocesses; quit the tool to return to the hub without relaunchingfestival(suspend → child → resume)
The home screen opens immediately. It shows installed-suite status, numbered navigation, and descriptions beside the menu in wide terminals. Short terminals scroll the menu to keep the selected action visible. Obey's screen reads its installation receipt before offering install or update; an unavailable read shows a retry action. Obey updates from this screen defer a running daemon's restart and report the command needed to activate the new version.
Progress animations respect FESTIVAL_REDUCED_MOTION=1.
festival install festival --channel stable
festival install obey # agent daemon + ob client
festival install app # Festival App, installed the standard way for this system
festival install app --format appimage # Linux: the AppImage even where apt is available
festival update app
festival uninstall app
festival update obey --no-restart # defer restart of an active daemon
festival update festival
festival outdated --json
festival update --all
festival list
festival list --json
festival browse --product fest --kind plugin
festival marketplace list
festival doctor
festival shell-init zsh
festival status --json
festival resolve camp
festival which camp --show-all
festival versionThe hub checks installed packages in the background. Open Updates to see
installed and available versions, update one package, or update all eligible
packages. Press r to refresh; failed or offline checks remain visible instead
of reporting that packages are current. Installed and catalog rows also show
available updates.
festival outdated checks without installing. festival update --all keeps
each installed source and channel, reports individual failures, and leaves
external/package-manager installs on their existing upgrade path. Successful
updates remain installed if another fails, so the same command can retry the
remaining packages. Bulk updates and the Updates screen defer running Obey
daemon restarts; the result names the restart command. Festival is updated last
and prompts you to restart the hub when its executable was replaced. Festival App is included: festival updates it in the format it was installed with, and never replaces a copy the App already updated itself.
JSON envelopes use schema version festival/v1alpha1.
| Code | When it happens | What to do |
|---|---|---|
E_APP_NOT_AVAILABLE |
The marketplace has no stable Festival App yet, or --channel is not stable |
Install from fest.build/app, or retry after the first stable release |
E_APP_PLATFORM |
There is no Festival App build for this operating system and architecture | Use a supported system: macOS (Apple silicon or Intel), Windows x64, Linux x64 |
E_APP_FORMAT_UNSUPPORTED |
--format outside Linux, --format deb without apt-get, or a format other than the installed one |
Drop --format, or run festival uninstall app before switching formats |
E_APP_SIGNATURE |
A marketplace signature, a sha256, or the App's update signature did not match; nothing was placed | Retry later and report it if it persists |
E_APP_BUNDLE_INVALID |
The downloaded macOS bundle failed its bundle id, version or code signature check | Report it; nothing was replaced |
E_APP_RUNNING |
Festival App is running from the location festival would change, or festival could not check | Quit Festival App and run the command again |
E_APP_FOREIGN |
Something at the install location is not Festival App, or festival's record disagrees with what is there | Move that item aside, then run the command again |
E_APP_ELEVATION |
The command ran as root, or the Linux password prompt was missing or dismissed | Follow the message: run as your normal user, use --format appimage, or run the printed sudo apt-get command |
E_APP_INSTALLER_FAILED |
The Windows installer or uninstaller, or apt-get, failed or did not leave the expected version; Windows blocked the installer | Read the message; Smart App Control blocks unsigned installers |
E_APP_DOWNLOAD_STALLED |
The download received no data for 60 seconds | Check the network and retry |
| Target | Effect |
|---|---|
festival, camp, fest |
Install the suite bundle obedience-corp/festival (camp + fest) |
obey |
Install the Obey daemon and ob client as a separate package |
app, festival-app |
Install Festival App (obedience-corp/festival-app), the desktop app, the standard way for this system (see Festival App) |
camp-<name>, fest-<name> |
Install a plugin from registered marketplaces |
Plugin release archives may include a top-level assets/ directory. Festival
installs its contents into ~/.obey/plugins/<plugin-name>/, records every file
in the package receipt, and removes only those receipt-owned files on
uninstall. Other archive content is not copied into the plugin runtime tree.
festival install app installs Festival App, the desktop app, from the signed marketplace. It installs only
stable releases. Until the first stable release is published, the command reports E_APP_NOT_AVAILABLE and
points to fest.build/app.
| System | What festival installs | Where it goes |
|---|---|---|
| macOS (Apple silicon or Intel) | The app bundle | /Applications/Festival App.app. An existing copy is replaced where it is. An account that cannot write to /Applications gets ~/Applications, and the output says so. A copy that belongs to another account is never touched; this account gets its own copy in ~/Applications. |
| Windows x64 | The App's own installer, run silently | %LOCALAPPDATA%\Festival App, with the Start menu entry and the Add or Remove Programs entry the App's installer creates |
| Debian and Ubuntu family | The .deb, through apt-get |
Owned by dpkg, so apt can remove it. The system asks for your password. The prompt names /bin/sh because festival runs one fixed script as root that copies the package into a root-owned directory, checks its sha256 against the signed value, and only then runs apt-get install on that copy. |
| Other Linux x64 | The AppImage | ~/.local/bin/festival-app, with a menu entry and icon under your XDG data directory. No password. |
On Debian and Ubuntu, --format appimage installs the AppImage instead and needs no password. An existing
install keeps its format; to switch, run festival uninstall app first.
Verification. Before anything is placed, festival checks the marketplace signatures, the artifact's sha256,
and the App's own update signature (key id A0880EE086F129E5). Any mismatch stops the install with
E_APP_SIGNATURE. On macOS festival also checks the bundle's identifier and code signature. festival does not
add a quarantine mark to the files it downloads, never re-signs the App, and never removes quarantine marks from
files it did not download.
Download staging. Verified downloads are staged under $FESTIVAL_HOME/app-downloads and removed after the install. On macOS and Linux that directory is mode 0700. Windows has no such mode: its privacy relies on the per-user ACL that %FESTIVAL_HOME% (under your profile) inherits.
Windows. Smart App Control blocks unsigned installers no matter how they were downloaded. On a PC where it is
on, festival install app reports that Windows blocked the installer (E_APP_INSTALLER_FAILED).
Existing copies. A Festival App you installed another way (for example from the DMG or the browser installer)
is replaced in place, and festival reports Replaced the existing Festival App at <path>. Anything at the install
location that is not Festival App is left alone (E_APP_FOREIGN). festival never replaces a running App: quit it
and run the command again (E_APP_RUNNING).
Updates. Festival App also updates itself. festival update app, festival outdated and
festival update --all compare the version on disk with the newest stable release, report a copy the App updated
as updated_by_app, and never replace it with an older release.
Status. festival status --json always reports the App in a top-level app object, with or without --plugin;
the tools list is unchanged.
"app": {"installed": true, "version": "0.2.1", "receipt_version": "0.2.0", "format": "app-bundle",
"location": "/Applications/Festival App.app", "adopted": false, "updated_by_app": true,
"latest": "0.2.1", "update_available": false, "note": null}When festival has no record of the App, installed is false and every other field is null. When festival has a
record but the App was removed another way (the Windows uninstaller, the Trash, apt remove), installed is false,
receipt_version, format and location come from the record, and note is removed outside festival. Running
festival install app installs it again; festival uninstall app clears the record.
Uninstall. festival uninstall app removes only the location festival recorded: the app bundle on macOS, the
App's own uninstaller on Windows, apt-get remove for the deb, and the AppImage with its menu entry and icon.
| Env | Role |
|---|---|
FESTIVAL_HOME |
Absolute path override for manager state |
Default: ~/.obey/installer with bin/, state.db, marketplace clones, receipts.
Requires Go 1.25.6 or newer (see go.mod).
just # list recipes
just build # bin/festival
just run version
just check # fmt + vet + lint + test
just test
just testing notty # no-TTY integration lane: builds the binary, drives it headless
just release all # cross-platform festival-{os}-{arch}
just ci # full gate: check + all four release builds + static-link checkcmd/festival/ # binary entry (bare → TUI, subcommands → CLI)
internal/app/ # service layer shared by CLI and TUI
internal/cli/ # cobra wrappers + human/JSON rendering
internal/tui/ # bubbletea manager (theme, anim, screens)
just release current # newest tag on each channel
just release tags # every release tag, newest first
just release stable patch dry-run # print the tag that would be cut, then stop
just release stable patch # guard, gate, annotated tag, push (also: minor, major)just release stable refuses unless main is checked out, clean, and level
with origin/main, then runs just ci as the gate before it creates the tag.
It stops at the tag push: .github/workflows/release.yml fires on the v* tag
and publishes the binaries, checksums, and release notes. This repo cuts stable
tags only; see .justfiles/build.just for why there is no rc or dev
channel.
| Package | Surface |
|---|---|
internal/state |
SQLite + WAL, home, config |
internal/state/receipts |
Install receipts |
internal/state/lock |
Cross-process install lock |
internal/verify |
Canonical JSON + Ed25519 verification and pinned trust |
internal/artifacts |
HTTPS download, bounded tar.gz, atomic move |
internal/source |
Marketplace clone cache + package index |
Apache License 2.0 - See LICENSE for details.
Suite installs and updates ask Camp to create a festival camp when no camps
are registered. Camp owns the shared completion record, so the desktop app and
CLI do not create duplicates, and updates do not recreate a deleted starter.
Existing camps are preserved. festival setup retries this step independently
of binary installation and completes setup after a package-manager install.
Run it as your regular user; root invocations defer workspace creation.
The JSON install/update result includes starter with an action and optional
path/message. A failed starter step leaves the successfully installed binaries
available and reports how to retry. Older Camp versions without setup report
a pending step until the suite is upgraded.
Obey installs and updates retain the optional Linux acquisition helper and its
installer under bin/libexec/obey, with both files in the managed receipt.
Incomplete payload pairs are refused before activation. An update can repair a
missing payload even when the installed Obey version is current, without a
daemon restart. Uninstall removes the user-owned payload, not a system helper
shared with other users.
festival setup integrations delegates administrator authorization to
obey terminal-input setup --authorize. The operating system owns the prompt;
background --check never prompts. Declined authorization remains a repairable
integration state. Already running provider processes can stay running.
The integration report advertises linux_terminal_input_setup. Festival App
uses this capability to reject a bundled installer that predates the complete
Linux install path. Publish the corresponding Obey release first, then this
installer, then update the App's sidecar pin. Development source staging is not
a substitute for updating the published pin.




