Eekaam CLI

The Eekaam CLI builds themes, ships apps and manages dev stores from your terminal. It is the fastest way to work on a theme — eekaam theme dev runs a local server with hot reload, so you edit a Liquid file and see the change without uploading anything by hand.

Install

Builds are published for macOS (Intel and Apple silicon), Linux (x64 and arm64) and Windows x64. The binary installs as eekaam.

Log in

This opens your browser, you approve the session, and the CLI stores the credentials in ~/.eekaam/config.json. Everything else assumes you are logged in.

Dev stores

Theme commands run against an active dev store. Create one, then select it:

Dev stores are free and disposable. eekaam store reset restores the sample catalogue when you have made a mess of it, and eekaam store transfer --email client@example.com hands a finished store to a client.

Working on a theme

theme dev watches the directory and pushes changes as you save. Useful flags:

The rest of the file commands:

Checking a theme

Validates structure and Liquid syntax against the same rules the upload pipeline applies, so a theme that passes here will not be rejected for structure. Run it before packaging. --fail-on-warning makes warnings exit non-zero, which is what you want in CI.

Managing themes on the store

Sharing a preview

Returns a URL a client can open without an Eekaam account. Expiry is in days, 7 by default, 30 maximum.

Packaging for the theme store

Runs theme check first, then writes a ZIP named {name}-{version}.zip. --output sets the path; --no-check skips validation, which is not recommended — the marketplace runs the same checks on upload and will reject what you skipped.

See Theme requirements for the rules, and The theme store for what happens after you upload.

Apps

app init scaffolds an app and writes its eekaam.app.toml manifest in the current directory. The manifest always subscribes to app/uninstalled and app/scopes_update, even with a local app URL. app install puts the draft on one of your own dev stores without admin approval, which is how you test before submitting.

Running an app locally

Opens a public tunnel to your local server, starts a dev session that points the app at it on one dev store, starts your dev server and opens the install. The dev session applies to your dev store only; the app's saved config and your manifest are not changed. It is refreshed every five minutes and ended when the command exits. The first run in a directory that is not linked yet deploys the manifest, to create the app.

Saving eekaam.app.toml while it runs pushes URL, scope, webhook and extension changes into the session. Press k to send a test webhook, g to open GraphiQL (at http://localhost:3457/graphiql), and q or Ctrl-C to stop. See Develop locally for the whole loop.

Deploying

Shows the diff between the manifest and the server, asks, then pushes. Webhooks with a local callback are left out, with a line saying so; app dev sends those in its dev session.

Versions and releases

app release makes an approved version the one stores run. Releasing an older approved version is how you roll back. --version takes a version label or id, and -y/--yes skips the confirmation.

Test webhooks

Sends a test webhook for a topic and reports the status and duration. It exits 1 when the app did not accept it. eekaam app webhooks trigger is the same command.

See Testing webhooks for what the payload contains.

Credentials

A project needs no .env: app dev passes every variable to your dev server. The CLI keeps the client secret in .eekaam/credentials.json (git-ignored), because Eekaam stores it hashed and cannot return it.

env show prints EEKAAM_CLIENT_ID, EEKAAM_CLIENT_SECRET, EEKAAM_WEBHOOK_SECRET and EEKAAM_SCOPES as KEY=value lines, each secret masked to its last four characters.

env pull writes the same four to .env, leaving your other keys alone. It does not write EEKAAM_APP_URL, which changes on every app dev run. --rotate issues a new client secret and invalidates the old one.

Environments

A project can keep one manifest per environment: eekaam.app.toml plus eekaam.app.<name>.toml files, each linked to its own app.

See Environments.

Checking an app

Runs the automated App review guidelines rules against the project in the current directory: its manifest and its source files. Each finding is an error or a warning, with its rule id. It exits non-zero when there is at least one error, so it can gate CI. Warnings alone do not fail it.

app submit runs the same checks first and stops if any error is found. --skip-checks submits without running them. Reviewers check every rule anyway, so skipping only moves a failure to review.

See Building an app for the full app lifecycle.

Command reference

Add --help to any command for its flags.

Configuration

Credentials and the active store live in ~/.eekaam/config.json. The CLI talks to https://api.eekaam.com by default; --api-url points it somewhere else, which you only need when working against a self-hosted or staging instance.