mirror of
https://github.com/stack-auth/stack.git
synced 2026-07-12 21:00:52 +08:00
122 lines
3.4 KiB
Plaintext
122 lines
3.4 KiB
Plaintext
---
|
|
title: "Hexclave CLI"
|
|
description: "Use the Hexclave CLI to manage config and run admin scripts"
|
|
sidebarTitle: "Hexclave 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 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 project list
|
|
```
|
|
|
|
## 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`.
|
|
|
|
## 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>
|