Documentation

the Aviary

Install and manage Feathers with the toowl aviary command.

the Aviary is toowl's Feather registry. First-party Feathers — Claude, Nest, MCP Hub, Scout — ship inside the binary and need no install. Everything else installs into ~/.config/toowl/plugins/ through the toowl aviary command.

Install a Feather

toowl aviary install https://example.com/my-feather/manifest.toml

The argument is a manifest URL. https:// is the production form; file:// works for testing a Feather you're building locally. toowl downloads the manifest, verifies the package against the checksum it declares, and verifies the publisher's signature against your trust store at ~/.config/toowl/aviary/trusted-keys.toml.

List what's installed

toowl aviary list

Prints each installed Feather's ID, version, and whether its publisher key was trusted at install time.

Remove a Feather

toowl aviary uninstall <FEATHER-ID>

Use the ID exactly as toowl aviary list prints it. Feathers hot-stop, so removing one does not require restarting toowl.

Trust model

An install is refused by default unless the publisher's key is already in your trust store. This is the whole point of the registry: a Feather is a subprocess on your machine with access to the HostApi, so an unsigned one is not a package, it's an executable of unknown origin.

toowl aviary install <MANIFEST-URL> --insecure

--insecure skips the publisher-key check. The install still verifies the package checksum, but nothing proves who built it. It is recorded with publisher_trusted=false and shows as untrusted in toowl aviary list. Use it for a Feather you compiled yourself; don't use it for one you were sent.

Publishing

Third-party publishing to the Aviary is not open yet — the signing trust root and key revocation are still being finalised, and we would rather ship that late than ship a registry that can't revoke a bad key. The package format and client are in place, so the surface won't change much.

You can build and run Feathers today without the registry: a subprocess Feather is a program speaking JSON-RPC over stdio, and toowl will load one from your plugins directory. See Authoring a Feather for the trait and lifecycle, and the wire protocol for the message reference.

Want to publish a Feather when the registry opens? Email us — we're keeping a list.