<!-- zibby-template-version: 1 -->
# /zibby-app-list — list your running Zibby Managed Apps + browse the catalog

You are helping the user see what hosted apps they have deployed (and optionally, what they could deploy).

Canonical docs: **https://docs.zibby.app/apps/listing**

## Two surfaces

| Surface | Command | Purpose |
|---|---|---|
| **Deployed instances** | `zibby app list` | What's running NOW under the user's projects |
| **Catalog browse** | `zibby app templates` | What's available to deploy (read-only) |

## List deployed instances

```
Bash(zibby app list)                          # all instances across all projects
Bash(zibby app list --project <projectId>)    # filter to one project
Bash(zibby app list --quiet)                  # JSON output for scripting
```

Output rows (default human format):
- `instanceId` — the `app-<short-hex>` ID to use in every other `/zibby-app-*` command
- `name` — friendly name (from `--name` at deploy time, or auto-generated)
- `appType` — catalog id (`n8n`, `grafana`, …) OR `goal` for free-form deploys
- `status` — `running | pending | failed | stopped | upgrading | destroying`
- `url` — public `https://*.apps.zibby.app` URL
- `project` — the project the instance lives under
- `createdAt` — when deployed

## Browse the catalog

```
Bash(zibby app templates)
Bash(zibby app templates --quiet)              # JSON
```

Output rows:
- `id` — what you pass to `zibby app deploy <id>`
- `name` — human-friendly title
- `description` — one-line summary
- `category` — `automation | observability | dev-tools | wikis | …`
- `architecture` — `arm64 | x86_64 | both`

## Steps

1. **What is the user asking?**
   - "What do I have running?" → `zibby app list`
   - "What can I deploy?" → `zibby app templates`
   - "Show me my n8n" → list, then filter by `appType=n8n` mentally

2. **Pick the right scope.**
   - If they have multiple projects and only want one project's apps, `--project <id>`. Use `/zibby-status` to get current project context.
   - If they want JSON for piping into jq, pass `--quiet`.

3. **Run the command:**
   ```
   Bash(zibby app list)
   ```

4. **Summarize for the user.** Don't just dump every row. Group by status, highlight any `failed` or stuck-`pending` rows that need attention, then list the `running` ones.

5. **Lead them to the next action.**
   - Multiple instances + user wants to interact with one → ask which `instanceId`.
   - User wants to clean up → suggest `/zibby-app-destroy` per row, or batch them.
   - User wants to add another → suggest `/zibby-deploy-app`.

## When the list is empty

The user hasn't deployed any apps yet. Don't show an empty table — say so plainly:
> "You don't have any Managed Apps deployed yet. Run `/zibby-deploy-app` to add one."

Optionally show `zibby app templates` so they can see what's available.

## Catalog gotchas

- The catalog is **frozen at CLI build time** for offline use. For the live source-of-truth list, run with `--remote` (when implemented) or check https://zibby.dev/apps.
- Some catalog entries have `architecture: arm64` only — they won't deploy to `--arch x86_64` and vice versa. The CLI 400s if mismatched; surface the error message.
- Catalog entries marked `goal-mode-only` exist for templates that can't be cleanly catalog'd (n8n historically was here; now it's catalog-promoted). Read the `description` field.