stack/docs-mintlify/guides/going-further/cli.mdx

---
title: "Stack CLI"
description: "Use the Hexclave CLI to initialize projects, manage config, and run admin scripts"
sidebarTitle: "Stack CLI"
---

import { hexclaveAgentRemindersText } from "/snippets/hexclave-agent-reminders.jsx";

<Visibility for="agents">
{hexclaveAgentRemindersText}
</Visibility>

The Hexclave CLI is published as `@hexclave/cli` and exposes the `stack` command. Use it for project setup, branch config workflows, and quick admin scripts.

## Install

Install the CLI globally to use the `stack` command from any project:

```sh title="Terminal"
npm install -g @hexclave/cli@latest
```

Then check that it is available:

```sh title="Terminal"
stack --help
```

You can also run any command without installing globally by prefixing it with `npx @hexclave/cli@latest`, for example:

```sh title="Terminal"
npx @hexclave/cli@latest init
```

## Global options

These options can be used before a subcommand:

| Option | Description |
| --- | --- |
| `--project-id <id>` | Project ID for commands that operate on one project. You can also set `STACK_PROJECT_ID`. |
| `--json` | Print JSON output for commands that support it, such as `project list` and `project create`. |
| `--version` | Print the CLI version. |

The CLI reads Hexclave endpoints from `STACK_API_URL` and `STACK_DASHBOARD_URL`. If unset, it uses Hexclave Cloud.

## Authentication

Log in with a browser:

```sh title="Terminal"
stack login
```

This stores `STACK_CLI_REFRESH_TOKEN` in the CLI credentials file. You can also provide it through the environment, which is useful in CI.

```sh title="Terminal"
STACK_CLI_REFRESH_TOKEN=<refresh-token> stack project list
```

Log out by removing the saved refresh token:

```sh title="Terminal"
stack logout
```

If you have an anonymous CLI session that should be linked during login, set `STACK_CLI_ANON_REFRESH_TOKEN` before running `login`.

## Initialize a project

Run the interactive setup wizard:

```sh title="Terminal"
stack init
```

The wizard can create a cloud project, create a local config file, or link an existing project. In interactive terminals, it can run an agent to apply the setup changes to your app. Use `--no-agent` to print manual setup instructions instead.

### Non-interactive init

Use `--mode` to skip prompts:

| Command | What it does |
| --- | --- |
| `stack init --mode create --apps authentication,teams` | Create `stack.config.ts` for local config-driven development. |
| `stack init --mode create-cloud` | Create a new Hexclave Cloud project and write keys to `.env`. |
| `stack init --mode link-config --config-file ./stack.config.ts` | Link setup instructions to an existing local config file. |
| `stack init --mode link-cloud --select-project-id <id>` | Write keys for an existing cloud project to `.env`. |

Other useful flags:

| Option | Description |
| --- | --- |
| `--apps <apps>` | Comma-separated app IDs to enable in `create` mode. |
| `--config-file <path>` | Existing config file for `link-config` mode. |
| `--select-project-id <id>` | Existing cloud project for `link-cloud` mode. |
| `--output-dir <dir>` | Directory where output files should be written. Defaults to the current directory. |
| `--no-agent` | Skip the setup agent and print manual instructions. |

## Project commands

List projects owned by the logged-in user:

```sh title="Terminal"
stack project list
```

Create a project:

```sh title="Terminal"
stack project create --display-name "My App"
```

Use `--json` when you want machine-readable output:

```sh title="Terminal"
stack --json project list
```

## Config commands

Pull branch config into a local TypeScript config file:

```sh title="Terminal"
stack --project-id <project-id> config pull --config-file ./stack.config.ts
```

By default, `config pull` refuses to overwrite an existing file. Add `--overwrite` when that is intended.

Push a local config file to branch config:

```sh title="Terminal"
stack --project-id <project-id> config push --config-file ./stack.config.ts
```

`config pull` requires `stack login`. `config push` supports either `stack login` or `STACK_SECRET_SERVER_KEY`.

When running in GitHub Actions, `config push` records `GITHUB_REPOSITORY`, `GITHUB_REF_NAME`, `GITHUB_SHA`, and the config file path as the config source when those environment variables are available.

## Execute admin JavaScript

`stack exec` runs JavaScript with a preconfigured `HexclaveServerApp` available as `hexclaveServerApp`.

```sh title="Terminal"
stack --project-id <project-id> exec "return await hexclaveServerApp.listUsers()"
```

The JavaScript is executed as an async function. Return values are printed as formatted JSON; `undefined` prints nothing.

<Warning>
  `stack exec` has server-level access to the selected project. It requires `stack login` and intentionally rejects `STACK_SECRET_SERVER_KEY` auth.
</Warning>