Deploy a project with an AI coding agent

The exact commands a coding agent runs to put a project folder live on *.gheima.ma: the one sign-in step for the person, and what to do when a step fails.

Last updated November 13, 2026

View as Markdown Open in Claude Open in ChatGPT

For a coding agent asked to "deploy this to gheima.ma". Run every command from the project folder with --json: stdout carries one JSON document, and an error goes to stderr as {"error":{"code","message"}}. The exit code says what happened: 0 ok, 2 a missing flag, 3 not signed in, 5 rejected, 7 timeout, 8 the deployment did not go live.

1. Get the CLI#

Shell

npx -y @gheima/cli@latest --version

Nothing to install: use npx -y @gheima/cli@latest wherever this page says gheima. It needs Node 20 or later. Without Node, curl -fsSL https://gheima.ma/install.sh | sh installs a standalone binary in ~/.local/bin.

2. Sign in: the one step for the person#

Shell

gheima whoami --json
# exit 0: already signed in, go to step 3. Exit 3: sign in below.
gheima login --no-wait --json
gheima login --resume --timeout 110 --json

1
Hand over the link
Tell the person, word for word: "Open <verificationUrl>, sign in or create an account, and approve the code <userCode>." Use the values login --no-wait printed.
2
Wait
Run gheima login --resume --timeout 110 --json once. Exit 0 means signed in: go on to step 3. Exit 7 with the code login_pending means the person has not approved yet: stop here, say you are waiting for their approval, and run login --resume again when they tell you they approved, rather than polling until the code runs out. The code expires after ten minutes; after that, start again with login --no-wait.

New accounts are by invitation during the beta. When the sign-in page says an invitation is needed, tell the person to request one from hello@gheima.ma, and stop until they have an account.

3. Deploy#

Shell

gheima deploy --yes --json

Done when it exits 0 with "status": "LIVE" and a "url". Give the person the url.

The first deploy in a folder creates a service, named after package.json or the folder (--name sets another), and links the folder in .gheima/. A folder of plain HTML files (an index.html and nothing that builds or runs a server) becomes a static site, which plans count apart from services (set the type yourself with --type). Later deploys reuse the service. Where the code comes from:

The folder has a git remote: Gheima builds the remote repository, on the current branch. Push first: commits that are only local are not deployed. A private GitHub repository also needs the Gheima GitHub App (see below).
No remote, or not a git repository: The folder is uploaded and built. Inside a git work tree the upload follows .gitignore; .env files and node_modules are always left out. Add --upload to upload even when there is a remote.

When a step fails#

Exit 8: the deployment did not go live: Read the build log with gheima logs --build, then the error code it names in https://gheima.ma/docs/errors.md. Fix the app, push (or not, for an upload), and run gheima deploy --json again.
Exit 3: not signed in: Go back to step 2.
Exit 2 naming --yes: The first deploy creates a service and asks first. Pass --yes once the person has asked for the deploy.
Exit 5: the name is taken: Pass another --name.
Exit 1 with code payload_too_large: the upload is too large: Leave build output and large assets out with .gitignore: the build installs dependencies and produces its output itself.
The build log says the repository was not found: The repository is private and Gheima cannot read it. Ask the person to install the Gheima GitHub App on it from https://gheima.ma/api/github/install, then deploy again. Or deploy the files with --upload.
Exit 7: timed out waiting: The deployment keeps going. Follow it with gheima services deployments <service> --json until it stops running: LIVE is live; FAILED, CANCELLED or SKIPPED carries an errorMessage saying why.

Over MCP#

With the Gheima MCP server connected (https://gheima.ma/mcp): gheima_services_create with a name and repoUrl, then gheima_services_deploy, then gheima_services_deployments until that deployment stops running (LIVE, or FAILED, CANCELLED or SKIPPED with an errorMessage), then gheima_services_get for the url. For a folder with no git remote, call gheima_services_create (a name, no repoUrl), then gheima_services_create_upload, and run the command it returns in the folder: it uploads the files and starts the deployment; then poll gheima_services_deployments the same way.