# 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.

Source: https://gheima.ma/docs/deploy-with-an-agent

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

```bash
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

```bash
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
```

login --no-wait prints userCode and verificationUrl and exits. login --resume waits for the approval.

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.

> Note: 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

```bash
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.

---

All docs: https://gheima.ma/docs.md