Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt

Use this file to discover all available pages before exploring further.

The Stack Auth CLI is published as @stackframe/stack-cli and exposes the stack command. Use it for project setup, branch config workflows, quick admin scripts, and the local emulator.

​
Install

Install the CLI globally to use the stack command from any project:
Terminal
npm install -g @stackframe/stack-cli@latest
Then check that it is available:
Terminal
stack --help
You can also run any command without installing globally by prefixing it with npx @stackframe/stack-cli@latest, for example:
Terminal
npx @stackframe/stack-cli@latest init

​
Global options

These options can be used before a subcommand:
OptionDescription
--project-id <id>Project ID for commands that operate on one project. You can also set STACK_PROJECT_ID.
--jsonPrint JSON output for commands that support it, such as project list and project create.
--versionPrint the CLI version.
The CLI reads Stack Auth endpoints from STACK_API_URL and STACK_DASHBOARD_URL. If unset, it uses Stack Auth Cloud.

​
Authentication

Log in with a browser:
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.
Terminal
STACK_CLI_REFRESH_TOKEN=<refresh-token> stack project list
Log out by removing the saved refresh token:
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:
Terminal
stack init
The wizard can create a cloud project, create a local config file for the emulator, 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:
CommandWhat it does
stack init --mode create --apps authentication,teamsCreate stack.config.ts for local config-driven development.
stack init --mode create-cloudCreate a new Stack Auth Cloud project and write keys to .env.
stack init --mode link-config --config-file ./stack.config.tsLink 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:
OptionDescription
--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-agentSkip the setup agent and print manual instructions.

​
Project commands

List projects owned by the logged-in user:
Terminal
stack project list
Create a project:
Terminal
stack project create --display-name "My App"
Use --json when you want machine-readable output:
Terminal
stack --json project list

​
Config commands

Pull branch config into a local TypeScript config file:
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:
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 StackServerApp available as stackServerApp.
Terminal
stack --project-id <project-id> exec "return await stackServerApp.listUsers()"
The JavaScript is executed as an async function. Return values are printed as formatted JSON; undefined prints nothing.
stack exec has server-level access to the selected project. It requires stack login and intentionally rejects STACK_SECRET_SERVER_KEY auth.

​
Local emulator commands

The CLI also manages the QEMU local emulator:
Terminal
stack emulator start
stack emulator status
stack emulator stop
See the local emulator guide for setup, ports, environment variables, and troubleshooting.