Groups & Teams¶
Every app on AppMecca belongs to exactly one group. A group is the unit of ownership and access control — apps, their env vars, their databases, their domains, all live inside a group, and only the group's members can see or act on them.
You never have to create one to get started: when you sign up, AppMecca
creates a personal group for you automatically (named after you, e.g.
"Euan's Group"), and mecca register <git-url> puts a new app there unless
you tell it otherwise. Team groups — shared with colleagues — are something
you create explicitly, when you want to.
Personal groups vs. team groups¶
| Personal group | Team group | |
|---|---|---|
| Created | Automatically, when you sign up | Explicitly, with mecca group create |
| Members | You, alone | You plus whoever you invite |
| Can be renamed | No | Yes |
| Can be deleted | No | Yes |
| Ownership can be transferred | No | Yes |
You can belong to any number of groups — your personal one plus as many team groups as you're invited to or create.
There's also a system group, and it isn't yours
A handful of apps belong to AppMecca's own system group — the
dashboard, the docs site, and similar platform infrastructure. You won't
see it in mecca group list, and you don't need to think about it; it
exists so those apps have an owner too.
Roles¶
Every membership carries a role, and roles are per-group — you can be the owner of one group and an ordinary member of another.
| Role | Can do |
|---|---|
member |
Deploy, view logs, manage env vars and everything else short of the two rows below |
administrator |
Everything a member can, plus invite/remove members and change their roles |
owner |
Everything an administrator can, plus rename or delete the group, and transfer ownership |
You're always the owner of your own personal group. owner isn't something
you grant with mecca group role (which only accepts member or
administrator) — the only way to make someone else the owner is
transferring ownership to them, which
simultaneously demotes you to administrator.
Creating a group¶
You become the owner. --name is a display name only — if you skip it, the
slug is used.
Seeing your groups¶
The → marks your active group for this environment — see below.
Your active group, and mecca use¶
Most commands need to know which group's app you mean. Rather than typing
--group <slug> on every single one, you can set a default for an
environment:
Every command you run against that environment from then on defaults to
@acme, until you switch again with mecca use <another-slug> or override
it for one command with --group.
mecca use needs a logged-in session
The active group is stored on your session, so mecca use only works
once you've run mecca login — it refuses outright if you're
authenticating with an API key alone. If your administrator scoped your
key to a specific group, that group behaves as your default; pass
--group explicitly on any command that needs a different one.
If you've never run mecca use for an environment, commands default to your
personal group — which is why a team app can "vanish" the moment you
switch machines or clear your session: nothing is wrong, you're simply back
to the default.
Naming a group with --group¶
--group <slug> is a flag on every command, and it always wins over
whatever your active group is:
Both forms are equivalent — --group works whether you put it before or
after the subcommand.
Listing apps across all your groups¶
mecca app list with no --group shows every app in every group you
belong to, not just your active one, with a Group column naming the
owner of each row:
App Slug Group Branch Status Health URL
Saldo saldo-website acme main running ok https://...
Ticket Uno go-ticket-uno gtu main running ok https://...
Pass --group <slug> to narrow it to one group, the same as any other
command.
Resolving an app name without a group flag¶
Commands that act on one app — mecca var, mecca app show, mecca
domain, mecca cron, and the rest — need to resolve the name you typed
down to a single app in a single group. If you don't say which group,
AppMecca resolves it against your active group (or your personal group, by
default). If the app you meant lives in a different one of your groups,
that lookup misses and you get "App not found" even though mecca app list
just showed it to you.
AppMecca is progressively teaching more commands to do better than that: on
those, if you name no group and the app name matches exactly one of your
own groups, it resolves there automatically — no --group needed. If it
matches more than one, the command refuses rather than guessing, and names
the groups it found:
Error (409)
'api' exists in more than one of your groups (acme, gtu). Name the one you mean: --group acme
(Pick one of the group slugs it lists — you don't pass more than one
--group.) Until every command has that behaviour, the reliable fix for
"App not found" is always the same: check the Group column in mecca app
list, then pass --group <slug> explicitly.
Why the same name can exist in two of your groups at once
App names only have to be unique within a group. If you're a member of
both @acme and @gtu, and each independently registered an app called
api, that's completely legitimate — and it's exactly what makes the
ambiguity above possible. It's a different, much rarer situation from
two different apps' names colliding into the same internal
identifier,
which AppMecca refuses at registration time so it can never happen.
Inviting people to a group¶
Invites are per-group and go to an email address. The invite itself doesn't create an account — the recipient signs in (or signs up, which on AppMecca is the same act) with that exact email, then accepts:
# You, as an owner or administrator of @acme:
mecca group invite acme --email dana@example.com -e dev
✓ Invited dana@example.com to @acme as member.
Token: 9f2c...
Recipient runs: mecca invite accept 9f2c...
Expires: 2026-09-08T09:02:11Z
--role administrator on the invite grants the administrator role instead
of the default member. To see or manage outstanding invites:
Managing members¶
mecca group members acme -e dev
mecca group role acme dana@example.com --role administrator -e dev
mecca group remove acme dana@example.com -e dev
Transferring ownership¶
Ownership can only be transferred to someone who is already a member of the group — invite them first if they aren't:
You become an administrator of the group; Dana becomes the owner. A personal group's ownership can never be transferred — there's nothing to transfer it to, since it only ever has one member.
Renaming, leaving, and deleting a group¶
mecca group rename acme --slug acme-corp -e dev
mecca group rename acme --name "Acme Corporation" -e dev
mecca group leave gtu -e dev
mecca group delete acme -e dev
delete is a soft-delete and can be reversed by support — it isn't
immediate, irreversible data loss. None of these four apply to your personal
group: it can't be renamed, you can't leave it, and it can't be deleted this
way.
A slug can't change while anything uses it
A group's slug is part of every app's URL in the group and of an NS-hosted
domain's zone tag, so mecca group rename <slug> --slug … is refused (409
slug_has_dependants, listing them) while the group has an app — any
branch, any state — or an NS-hosted domain. Use --name instead, or first
delete those apps (mecca app delete) and release those domains
(mecca domain ns-release).
If a rename, a group delete, mecca register, a build or mecca domain ns-setup
answers another change to this group is in progress; retry in a few seconds
(409 group_busy), another change is holding the group for a moment — run the
command again.
Your group's Audit log in the dashboard also lists changes a platform operator made to the group. It shows them as a platform administrator: group members are not shown which operator it was, nor their IP address or browser.
Command reference¶
| Command | Does |
|---|---|
mecca group create <slug> |
Create a group; you become owner |
mecca group list |
List your memberships |
mecca group show [slug] |
Show one group (defaults to your active one) |
mecca group use <slug> / mecca use <slug> |
Set the active group for this environment |
mecca group rename <slug> |
Change slug and/or display name |
mecca group members <slug> |
List members and their roles |
mecca group invite <slug> --email <addr> |
Invite someone (owner/administrator only) |
mecca group invites <slug> |
List outstanding invitations |
mecca group uninvite <slug> --email <addr> |
Revoke a pending invitation |
mecca invite accept <token> |
Accept an invitation you received |
mecca group role <slug> <email> --role <role> |
Change a member's role |
mecca group remove <slug> <email> |
Remove a member |
mecca group transfer <slug> --to <email> |
Transfer ownership |
mecca group leave <slug> |
Leave a group |
mecca group delete <slug> |
Soft-delete a group (owner only) |