mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-16 21:08:38 +08:00
c91a23ee88
Step 5: rename lowercase local vars stackApp/stackServerApp/stackClientApp/ stackAdminApp -> hexclave* across SDK source, apps, examples, and docs-mintlify (docs/ excluded). Public StackServerApp/StackClientApp classes and the useStackApp hook are unchanged. typecheck + lint green.
151 lines
4.7 KiB
Plaintext
151 lines
4.7 KiB
Plaintext
---
|
|
title: "Stack CLI"
|
|
description: "Use the Hexclave CLI to initialize projects, manage config, and run admin scripts"
|
|
sidebarTitle: "Stack CLI"
|
|
---
|
|
|
|
import { HexclaveAgentReminders } from "/snippets/hexclave-agent-reminders.jsx";
|
|
|
|
<HexclaveAgentReminders />
|
|
|
|
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>
|