appctl app
appctl app manages the global registry of known apps so you never have to
type --app-dir /long/path/.appctl again. It works the same way
kubectl config, aws profiles, and git worktrees solve their own
context-switching problems.
appctl app <COMMAND>Commands
Section titled “Commands”| Command | What it does |
|---|---|
appctl app add [NAME] | Register the current directory’s .appctl/ (or --path) under a name and set it active. Optional NAME defaults to the parent directory name. Put flags before the name, e.g. appctl app add --display-name "My API" --description "…" myapi. With --openapi (and related sync flags) it can run a sync in that app directory. Use --force for that built-in sync when a schema.json already exists — the same rules as appctl sync. |
appctl app list | Show every registered app, which one is active, and the absolute path to its .appctl directory. The active app is marked with *. |
appctl app use <NAME> | Switch the globally active app by name. |
appctl app remove <NAME> | Unregister an app. Files on disk are not touched. |
The registry lives at ~/.appctl/apps.toml:
active = "backend"
[apps]backend = "/Users/you/projects/api-backend/.appctl"dashboard = "/Users/you/projects/admin-dashboard/.appctl"How appctl picks an app
Section titled “How appctl picks an app”Every command (chat, run, sync, doctor, serve, history, config,
plugin, auth, mcp) resolves the active app in this exact order and stops
at the first match:
--app-dir <PATH>— explicit per-command override.- Auto-detect — walks up from the current working directory looking for
an
.appctl/folder. If you are anywhere inside a project that was initialized withappctl init, it is picked automatically. - Global active app —
activein~/.appctl/apps.toml. - Otherwise the command errors out with a hint to run
appctl initorappctl app use <name>.
appctl init now offers to register the project globally as part of setup, so
for most projects you no longer need to run appctl app add manually unless
you skipped that prompt or want a custom name.
The resolved app label shows up in the chat prompt so you always know which context you are in:
appctl[backend · gemini]▶Typical workflow
Section titled “Typical workflow”Initialize two projects:
cd ~/projects/api-backendappctl init# answer "yes" when init asks to register globally
cd ~/projects/admin-dashboardappctl init# answer "yes" when init asks to register globallyInspect the registry:
$ appctl app list* backend -> /Users/you/projects/api-backend/.appctl dashboard -> /Users/you/projects/admin-dashboard/.appctlSwitch globally and chat from anywhere:
cd ~appctl app use dashboardappctl chat # uses dashboardOr rely on auto-detect:
cd ~/projects/api-backend/srcappctl chat # auto-detects backend, ignores the global active appExplicit override for one command:
appctl --app-dir /tmp/experiment/.appctl chatRegister and sync in one step:
appctl app add storefront \ --path /Users/you/projects/storefront/.appctl \ --openapi http://127.0.0.1:8000/openapi.json \ --base-url http://127.0.0.1:8000 \ --forceRemoving an app
Section titled “Removing an app”appctl app remove only unregisters the app from ~/.appctl/apps.toml. Your
.appctl/ directory, history, and secrets are untouched. Delete the folder
manually if you want to wipe the app.
appctl app remove dashboardRelated
Section titled “Related”appctl init— create a new.appctl/in the current folder.appctl chat— the prompt that displays the active app.appctl config— inspect per-app configuration.