Skip to content

About

Festival hub: installs, updates and launches the camp and fest CLI suite from a signed marketplace

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

festival

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.

Automatic terminal setup

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 again

The 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.

Earlier walkthroughs

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

festival TUI first run: the setup card on a fresh home, the four step getting started tour, and the PATH block shown before it is written

Home: boot splash, ambient flame, multi-activity booths, menu → doctor

festival TUI: boot splash, fire ambient, multi-activity booths, and home menu

Channels: install channel picker, shell/PATH, installed list

festival TUI: install channel picker, shell/PATH guidance, and the installed packages list

Community: run festival, select Join our Discord, and open the invite

Running festival, selecting Join our Discord, and opening the Obedience Corp 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

festival TUI launchpad: opening camp as a child tool and returning to the hub on quit

Reproduce locally:

just build
just vhs all   # requires vhs, ttyd, ffmpeg

Install

npm / pnpm / bun:

npm install -g @obedience-corp/festival

macOS:

brew install --cask Obedience-Corp/tap/festival

Arch Linux:

yay -S festival-bin

Shell script (macOS and Linux):

curl -fsSL https://raw.githubusercontent.com/Obedience-Corp/festival/main/install.sh | bash

Each 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.

Trust model

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.

Quick start (humans)

just build          # → bin/festival
./bin/festival      # opens the TUI on a terminal

The 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 + ob or 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 relaunching festival (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.

CLI (scripts / agents)

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 version

The 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.

Festival App error codes

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

Install targets

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 App

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.

Home directory

Env Role
FESTIVAL_HOME Absolute path override for manager state

Default: ~/.obey/installer with bin/, state.db, marketplace clones, receipts.

Build from source

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 check

Layout

cmd/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)

Releasing

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.

What works under the hood

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

License

Apache License 2.0 - See LICENSE for details.

Starter camp

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.

Linux terminal input

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.

About

Festival hub: installs, updates and launches the camp and fest CLI suite from a signed marketplace

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages