# CLI

```sh
npx hostedge login     # opens your browser to authorize
npx hostedge deploy    # uploads changed files and streams the build
```

## Install

Run it without installing (`npx hostedge`), or install it once:

```sh
npm install --global hostedge
# or
curl -fsSL https://hostedge.app/install.sh | sh
```

It needs Node.js 20.11 or newer. Then `hostedge login` and `hostedge deploy` work from any folder.

## Commands

| Command                 | What it does                                                                                                                                                          |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hostedge login`        | Opens HostEdge in your browser; pick a workspace and the CLI receives a 90-day token. `--token <token>` skips the browser; `--with-token` reads the token from stdin. |
| `hostedge logout`       | Forgets the token on this computer. Revoke it in **Settings › API tokens**.                                                                                           |
| `hostedge whoami`       | The account, workspace and scopes in use.                                                                                                                             |
| `hostedge ai-kit`       | Writes `AGENTS.md`, `CLAUDE.md`, a Cursor rule and a Claude Code skill. See [Agent kit](https://hostedge.app/docs/agent-kit). `--force` overwrites.                                       |
| `hostedge init`         | Links the folder to a new or existing project (`--project <slug>`). Writes `.hostedge/project.json` and adds it to `.gitignore`. `--ai` also writes the agent kit.    |
| `hostedge deploy`       | Deploys the folder. `--preview` for a preview, `-m` for a message, `--no-wait` to return after queueing. Exits with 5 if the build fails.                             |
| `hostedge logs`         | Runtime logs. `-f` follows, `--level error`, `--search <text>`, `--since 30m\|1h\|24h\|7d`.                                                                           |
| `hostedge env pull`     | Writes variables to `.env.local` (mode 600, git-ignored). `-e production` for another environment.                                                                    |
| `hostedge share [port]` | A public HTTPS link (and QR code) to a dev server on your computer, to try it on your phone. See [Share localhost](https://hostedge.app/docs/share-localhost).                            |

The first `hostedge deploy` in an unlinked folder creates the project and links it.

## Scripts and agents

Every command takes these options:

| Option            | Effect                                                                                                          |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `--json`          | Machine-readable output on stdout (NDJSON for `logs`). Progress and human text go to stderr, never to stdout.   |
| `-y`, `--yes`     | Never prompt. `CI=1` and a missing terminal do the same; commands fail with a clear message instead of waiting. |
| `-q`, `--quiet`   | Only results and errors. `hostedge deploy -q` prints only the URL.                                              |
| `--api-url <url>` | Use another HostEdge for this run (same as `HOSTEDGE_API_URL`).                                                 |
| `--no-color`      | Plain text. `NO_COLOR` is respected too.                                                                        |

```sh
hostedge deploy --wait --json
# {"deploymentId":"dep_…","status":"ready","url":"https://….hostedge.app","failureReason":null,…}
```

If the build fails the same JSON is printed with `"status":"failed"` and the reason in `failureReason`, and the exit code is 5. Tokens are never printed: use `HOSTEDGE_TOKEN`, or pipe one to `hostedge login --with-token`.

### Exit codes

| Code | Meaning                                                                 |
| ---- | ----------------------------------------------------------------------- |
| 0    | Success                                                                 |
| 1    | Generic failure                                                         |
| 2    | Usage error (unknown flag or command, missing input)                    |
| 3    | Authentication error (not signed in, token invalid, expired or revoked) |
| 4    | Not found (project, deployment or linked folder)                        |
| 5    | Deployment failed or was canceled                                       |
| 6    | A plan limit was reached                                                |

More in [Agent kit](https://hostedge.app/docs/agent-kit).

## Continuous integration

Create a token in **Settings › API tokens** with the `deployments:write` and `projects:read` scopes, store it as a secret, and run:

```yaml
- run: npx hostedge deploy --message "${{ github.sha }}"
  env:
    HOSTEDGE_TOKEN: ${{ secrets.HOSTEDGE_TOKEN }}
```

## What gets uploaded

The same rules as the dashboard: `.git`, `node_modules` and similar folders are skipped, files that look like secrets are left behind with a note, and symbolic links are refused.