Installing the CLI¶

The mecca CLI is a Node package that you install on your local machine. It's how you interact with the AppMecca platform — building images, deploying apps, checking logs, and more.

Install¶

Both routes install the same package from npm.

Right now the two routes can differ by a version

Homebrew pins an explicit release; npm installs whatever the latest tag points at. Those are temporarily out of step — npm pins latest to a package's first publish, so with only pre-releases out it can sit on an older one.

Ask the registry rather than trusting this page, which cannot know when the two reconverge:

npm view appmecca dist-tags

If latest is behind, install that one version explicitly, once — npm install -g appmecca@0.1.0-alpha.4 or whatever alpha reports.

⚠ Do not pin @alpha as a habit. Once a stable release ships, latest tracks stable and an @alpha pin would silently hold you on pre-releases for good. It is a one-off correction, not a setting.

Homebrew (macOS)¶

brew tap appmecca/tap https://gitlab.com/appmecca-public/appmecca-homebrew-tap.git
brew trust appmecca/tap
brew install appmecca      # or: brew install mecca — same formula

Homebrew pulls Node in as a dependency, so you do not need it installed first. brew upgrade works normally afterwards.

Both of the one-time steps are structural, not optional:

The long-form tap URL — brew tap user/repo resolves to GitHub, and this tap is on GitLab, so the URL must be given explicitly.
brew trust — Homebrew 6 refuses to load a formula from an untrusted third-party tap. Skipping it makes brew install fail rather than prompt.

npm¶

npm install -g appmecca

Requires Node ≥ 22.19. npx appmecca <command> works too, without installing.

The package is appmecca; the command is mecca

Installing the appmecca package puts exactly one executable on your PATH: mecca. That's the CLI in this guide. The package name and the command name differ because the package's bin map says so.

On Homebrew, brew install appmecca and brew install mecca are the same formula — appmecca is an alias. Neither installs a binary called appmecca.

pip and pipx do not work

Nothing is published to PyPI — pip install appmecca fails, and always has. An older version of this page said otherwise; it was wrong. The CLI is distributed through npm and Homebrew only.

appmecca is a different tool

The administrator CLI used for provisioning and tearing down environments is also called appmecca, but it is a separate program installed by cloning its repository — never from npm, Homebrew or PyPI. If a page tells you to run an appmecca … command, that's a task for your platform administrator.

Verify Installation¶

mecca --version

You should see something like:

0.1.0-alpha.3

Alpha versioning is expected

The CLI is published as a pre-release while the TypeScript rewrite lands. The exact number moves with each release — treat the one above as a shape, not a target. npm install -g appmecca@alpha always takes the newest pre-release.

Configure API Access¶

The mecca CLI is a thin HTTP client that talks to the deployed AppMecca API — it does not need any cloud-provider credentials. Instead, it needs to know where the API is and how to authenticate.

The API URL is stored in ~/.appmecca/mecca.conf. Set it yourself with mecca configure -e <env> (below); your administrator gives you the URL.

Each environment gets its own section in mecca.conf with its API URL and environment name.

Cloud credentials are for administrators only

Only the appmecca admin CLI needs cloud credentials (for infrastructure setup/teardown). If you're an app developer using mecca, all you need is the API URL and an account on the environment.

Configure Default Environment¶

If you're always working with the same environment (e.g., dev), configure a default so you don't have to type -e dev on every command:

mecca configure -e dev

This runs an interactive setup that stores the API URL and default environment in ~/.appmecca/mecca.conf. No api-key prompt — authentication happens separately via mecca login (the resulting session token supersedes any key on disk).

To see all configured environments:

mecca configure list

To test connectivity to a configured environment:

mecca configure test -e dev

With a default environment set:

# Instead of:
mecca app deploy -e dev myapp

# You can just run:
mecca app deploy myapp

Explicit flags always win

If your default is dev but you run mecca app deploy -e staging myapp, it uses staging. The -e flag always overrides the configured default.

Set a Default App¶

If you're always working with the same app, set an environment variable. It supplies the default for the -a/--app option on filter-style commands (e.g. mecca queue list -a myapp, mecca build list --app myapp):

export APPMECCA_APP=myapp

Environment resolution order

mecca resolves the environment from, in order: the explicit -e/--env flag → the APPMECCA_ENV environment variable → the [default] section of ~/.appmecca/mecca.conf.

There is no APPMECCA_BRANCH

Branch is not settable via an environment variable. Pass -b/--branch explicitly; commands that take it default to main, except those that default to the app's registered branch.

Note that most mecca commands take the app as a positional argument (mecca app deploy myapp), which APPMECCA_APP does not fill in — it only backs the -a/--app option.

Git Authentication¶

AppMecca builds your Docker images by cloning your Git repository. If your repo is private, the build needs credentials that can reach it.

Link Your Git Account (Recommended)¶

The quickest way is to link your GitHub or GitLab account from the dashboard at https://dashboard.<env>.appmecca.net, then register your app through the repository picker. AppMecca binds that identity to the app, and every build clones with it — no key handling on your side. See Private Repositories for details.

SSH Deploy Keys¶

For CI/CD pipelines or shared environments, your administrator sets up a per-environment SSH deploy key using the admin CLI (these are not mecca commands — you cannot run them yourself):

# Administrator generates an SSH key for the environment
appmecca git-auth setup -e dev

# Administrator displays the public key
appmecca git-auth show-key -e dev

The administrator gives you the public key, and you add it as a deploy key in your Git hosting provider:

GitHub: Repository Settings → Deploy Keys → Add Deploy Key
GitLab: Repository Settings → Repository → Deploy Keys

One key per environment

Each AppMecca environment has its own SSH key. If you deploy to both dev and staging, your administrator needs to set up keys for both. These commands live on the appmecca admin CLI (not mecca) because they write to the platform secret store.

Authentication¶

mecca is the tenant CLI — every user has their own session bound to their email + group memberships. There are two ways to authenticate:

Option 1: Tenant session (the normal flow)¶

Sign in straight from the CLI (or on the dashboard at https://dashboard.<env>.appmecca.net, whichever you prefer):

mecca login you@example.com -e dev

⚠ There is no password. The command opens a browser to an authorize screen that says which machine is being granted access, for how long, and how to revoke it; approve it there and the CLI receives its session.

⚠ Signing up and signing in are the same act — mecca signup exists as a friendlier name for a first-time user, but login on an address with no account creates one. (mecca register <git-url> is unrelated: that registers an app.)

If you cannot open a browser on this machine, pass --no-browser and the URL is printed for you to open elsewhere.

The session token is stored at ~/.appmecca/session.json (mode 0600, per-environment). Verify with:

mecca whoami -e dev

Output shows your resolved scope: Logged in as <email> + your group memberships. When you list apps you'll see Apps (env · group: your-team) — scoped to apps in your group only.

To log out:

mecca logout -e dev

Option 2: API key (CI / scripts)¶

For non-interactive use, ask your administrator to mint a per-user api-key scoped to what your pipeline needs (read, deploy, or admin). There is no mecca api-key command — key creation is an administrator operation.

Use the key via the env var (preferred — no on-disk footprint):

export APPMECCA_API_KEY=am_k1_abc123...

Or persist it in mecca.conf for that env. mecca configure doesn't prompt for keys, so add the line by hand:

[dev]
environment = dev
api_url = https://api.dev.appmecca.net
api_key = am_k1_abc123...

Auth priority

mecca prefers a session over an api-key. Order: APPMECCA_API_KEY env var → session token from ~/.appmecca/session.json → api-key from ~/.appmecca/mecca.conf → EdDSA SSH key. The first successful method wins.

⚠️ Don't store the platform-admin root key in `mecca.conf`¶

The appmecca config api-key generate command (admin-side) writes the platform admin root key to ~/.appmecca/appmecca.conf — NOT mecca.conf. This separation is deliberate:

~/.appmecca/appmecca.conf — admin credentials read by the appmecca CLI.
~/.appmecca/mecca.conf — tenant config read by the mecca CLI. mecca configure writes only the API URL; api-keys (if you use one) are added by hand or via APPMECCA_API_KEY.

If you ever see a yellow banner in mecca output:

⚠ Acting as platform admin via api-key — mecca is the tenant CLI.
  Run: mecca logout --clear-keys && mecca login

…then a platform-admin api-key has ended up in mecca.conf (older fresh-env setups did this automatically; the current appmecca config api-key generate does not). To scrub it and drop to anonymous:

mecca logout --clear-keys -e dev    # revoke session AND scrub admin api-key
mecca login you@… -e dev            # log in as yourself

The --clear-keys flag specifically removes the api_key line from mecca.conf while preserving the api_url. Suppress the banner in scripts that intentionally use the admin key with MECCA_QUIET_SCOPE_BANNER=1.

Verify Everything Works¶

Confirm the CLI can reach the environment's API and that you're authenticated:

mecca configure test -e dev   # connectivity
mecca whoami -e dev           # who the API thinks you are

If both succeed, you're ready to go. Head to the Quick Start to deploy your first app.

Command Reference¶

Run mecca --help to see all available commands:

mecca --help

Every command group also has its own help:

mecca app --help      # deploy, redeploy, retry, logs, backup, publish/protect, …
mecca build --help    # trigger, status, logs, list
mecca var --help      # environment variables
mecca queue --help    # inspect and cancel queued actions