Hexclave CLI

The Hexclave CLI is published as @hexclave/cli and provides the hexclave command for project setup, development environments, configuration, deployments, administration, and team management.

Install and quickstart

Install the CLI globally if you want to use hexclave from any project:

Terminal

npm install -g @hexclave/cli@latest
hexclave --help

You can also run it without a global install:

Terminal

npx @hexclave/cli@latest --help
pnpm dlx @hexclave/cli@latest --help

For a project-local installation, add @hexclave/cli as a development dependency and run it with your package manager:

Terminal

pnpm add -D @hexclave/cli
pnpm exec hexclave --help

The CLI stores login credentials locally. For CI and other automation, use the environment variables described below instead of putting secrets in command history.

Authentication and environment

Run hexclave login to authenticate in a browser. The CLI stores the resulting refresh token locally. hexclave logout removes the stored token. The preferred current environment variables are:

Variable	Purpose
`HEXCLAVE_API_URL`	API base URL
`HEXCLAVE_DASHBOARD_URL`	Dashboard base URL
`HEXCLAVE_PROJECT_ID`	Default cloud project ID
`HEXCLAVE_SECRET_SERVER_KEY`	Server-key authentication for commands that support it

STACK_API_URL, STACK_DASHBOARD_URL, STACK_PROJECT_ID, and STACK_SECRET_SERVER_KEY are retained as backwards-compatible aliases for the corresponding HEXCLAVE_* variables. If both names for one setting are set to different values, the CLI reports an error. The CLI credential variables are currently named STACK_CLI_REFRESH_TOKEN and STACK_CLI_ANON_REFRESH_TOKEN. Use STACK_CLI_REFRESH_TOKEN for CI or other noninteractive login, and set STACK_CLI_ANON_REFRESH_TOKEN to link an anonymous session during login. The CLI defaults to Hexclave Cloud (https://api.hexclave.com and https://app.hexclave.com) when endpoint variables are not set. The root --json option enables JSON output for commands that support it. Commander also provides -V, --version and -h, --help on every command; the automatically generated help option is omitted from the individual option tables below.

Command reference

`hexclave init`

Synopsis

hexclave init [options]

Description Initialize Hexclave in a project. The wizard can create a development-environment config, create a cloud project, or link an existing config or cloud project. Options

Option	Description
`--mode <mode>`	Noninteractive mode: `create`, `create-cloud`, `link-config`, or `link-cloud`.
`--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>`	Cloud project ID for `link-cloud` mode.
`--output-dir <dir>`	Directory for generated files. Defaults to the current directory.
`--no-agent`	Skip the Claude agent and print setup instructions instead.
`--display-name <name>`	Project display name for `create-cloud` mode.

Behavior and authentication Without mode or link flags, the command is interactive. Noninteractive environments must provide an explicit mode or link option. Incompatible combinations such as --config-file with --select-project-id are rejected. The command writes project setup files, registers the Hexclave MCP server, and can run the Claude setup agent unless --no-agent is used.

Terminal

hexclave init --mode create

`hexclave doctor`

Synopsis

hexclave doctor [options]

Description Check that Hexclave is correctly wired up in a project. Options

Option	Description
`--output-dir <dir>`	Project root to inspect. Defaults to the current directory.
`--framework <fw>`	Override framework detection: `next`, `react`, or `js`.
`--json`	Emit a machine-readable report. The root `--json` option has the same effect.

Behavior and authentication The command reads package.json, detects or validates the framework, runs integration checks, prints pass/fail/warning results, and exits with status 1 if any check fails.

Terminal

hexclave doctor --framework next --json

`hexclave fix`

Synopsis

hexclave fix [options]

Description Use an AI agent to fix a Hexclave error in the current project. Options

Option	Description
`--error <text>`	Error message to fix. The command also accepts piped stdin.
`-y, --yes`	Skip the confirmation prompt.

Behavior and authentication If no error is supplied, the CLI reads stdin or prompts interactively. Error input is limited to 8,000 characters. In noninteractive environments, provide --error; confirmation is required unless --yes is supplied.

Terminal

printf '%s\n' "$HEXCLAVE_ERROR" | hexclave fix --yes

Synopsis

hexclave login

Description Log in to Hexclave through the browser-based CLI authentication flow. Options None. Behavior and authentication The refresh token is saved as STACK_CLI_REFRESH_TOKEN in the CLI credentials file. Set STACK_CLI_ANON_REFRESH_TOKEN before logging in to attach the login to an existing anonymous session; the anonymous token is removed after a successful link.

`hexclave logout`

Synopsis

hexclave logout

Description Remove the locally stored CLI refresh token. Options None. Behavior and authentication This removes the local credential. It does not require an API request.

`hexclave whoami`

Synopsis

hexclave whoami

Description Show the currently logged-in Hexclave CLI user. Options

Option	Description
`--json`	Root option; print user and team details as JSON.

Behavior and authentication Requires a login session. Human output includes user identity, email verification, anonymous/restricted status, team count, API URL, and dashboard URL.

`hexclave project`

Manage projects.

`hexclave project list`

Synopsis

hexclave project list [options]

Description List projects owned by the current user. By default, both cloud and development-environment projects are included. Options

Option	Description
`--cloud`	Only list cloud projects.
`--local`	Only list development-environment projects.
`--json`	Root option; print project objects as JSON.

Behavior and authentication --cloud and --local cannot be combined. Listing cloud projects requires a login session; listing local development-environment projects uses local state. Human-readable output contains the project ID, display name, and [cloud] or [local] target.

Terminal

hexclave project list --cloud

`hexclave project create`

Synopsis

hexclave project create [options]

Description Create a new cloud project. Options

Option	Description
`--cloud`	Required confirmation that this command creates a cloud project.
`--display-name <name>`	Project display name.
`--team-id <id>`	Team that owns the project.
`--json`	Root option; print the created project as JSON.

Behavior and authentication The command currently creates cloud projects only, so --cloud is required. It requires a login session. Missing display names can be entered interactively; in a noninteractive environment, provide --display-name.

Terminal

hexclave project create --cloud --display-name "My App"

`hexclave config`

Manage project configuration files.

`hexclave config pull`

Synopsis

hexclave config pull [options]

Description Pull the selected cloud branch configuration into a local TypeScript file. Options

Option	Description
`--cloud-project-id <id>`	Cloud project ID. Defaults to `HEXCLAVE_PROJECT_ID` or its `STACK_PROJECT_ID` compatibility alias.
`--config-file <path>`	Output path. Defaults to `./hexclave.config.ts` in the current directory.
`--overwrite`	Replace the file if it already exists.

Behavior and authentication This command requires hexclave login; secret-server-key-only authentication is rejected. The target must have a .ts extension. Existing files are protected unless --overwrite is supplied.

Terminal

hexclave config pull --cloud-project-id <project-id> --config-file ./hexclave.config.ts

`hexclave config push`

Synopsis

hexclave config push [options]

Description Push a local JavaScript or TypeScript config file to a cloud branch. Options

Option	Description
`--cloud-project-id <id>`	Cloud project ID. Defaults to `HEXCLAVE_PROJECT_ID` or its `STACK_PROJECT_ID` compatibility alias.
`--config-file <path>`	Required path to a `.js` or `.ts` config file.
`--source <type>`	Explicit source type. Only `github` is supported.
`--source-repo <owner/repo>`	GitHub repository. Only valid with `--source github`.
`--source-path <path>`	Config path inside the source repository. Only valid with `--source github`.
`--source-workflow-path <path>`	Syncing workflow path inside the source repository. Only valid with `--source github`.

Behavior and authentication This command accepts either hexclave login or HEXCLAVE_SECRET_SERVER_KEY authentication. GitHub Actions metadata is inferred from GITHUB_REPOSITORY, GITHUB_REF_NAME, and GITHUB_SHA when available. Explicit GitHub source metadata requires all corresponding source options.

Terminal

hexclave config push --cloud-project-id <project-id> --config-file ./hexclave.config.ts

`hexclave dev`

Synopsis

hexclave dev --config-file <path> -- <command> [args...]

Description Run a command with Hexclave development-environment credentials. Options and arguments

Argument or option	Description
`--config-file <path>`	Required config file path. Use `hexclave.config.ts`.
`<command...>`	Required command and arguments after `--`.

Behavior and authentication The CLI starts or reuses the development dashboard, creates a development-environment session, injects the project’s API URL, dashboard URL, project ID, and related environment variables into the child process, then forwards signals and cleans up when the child exits. The command accepts the config path supplied by the user; current project setup uses hexclave.config.ts.

Terminal

hexclave dev --config-file ./hexclave.config.ts -- npm run dev:inner

`hexclave deploy`

Synopsis

hexclave deploy <service> [options]

Description Deploy a service defined under deploy.services in hexclave.config.ts. The CLI uploads the service source, waits for Vercel to accept the deployment, and prints the run ID without waiting for the remote build to finish. Options

Option	Description
`--config <path>`	Config file path. If omitted, the CLI auto-discovers `hexclave.config.ts` in the current directory.
`--cloud-project-id <id>`	Cloud project ID. Defaults to `HEXCLAVE_PROJECT_ID` or its `STACK_PROJECT_ID` compatibility alias.
`--secret <KEY=VALUE>`	Secret value for a deployment environment variable. Repeatable.

Behavior and authentication Authentication uses HEXCLAVE_SECRET_SERVER_KEY when set, which is recommended for CI; otherwise it uses the hexclave login session. Every secret referenced by the service must be supplied, and unknown secret keys are rejected. Secret values are sent to the deployment target and are not persisted by Hexclave.

Terminal

hexclave deploy web --config ./hexclave.config.ts --secret DATABASE_PASSWORD="$DATABASE_PASSWORD"

`hexclave exec`

Synopsis

hexclave exec [javascript] [options]

Description Execute JavaScript as an async function with a preconfigured HexclaveServerApp available as hexclaveServerApp. Options

Option	Description
`--cloud-project-id <id>`	Cloud project ID to run against. Use `--config-file` for a development environment.
`--config-file <path>`	Development-environment config file. Use `--cloud-project-id` for the cloud API.

Behavior and authentication Pass exactly one JavaScript argument. Cloud execution requires hexclave login and intentionally rejects HEXCLAVE_SECRET_SERVER_KEY authentication. Development-environment execution resolves access from the supplied config file. Non-undefined return values are printed as formatted JSON; undefined prints nothing.

Terminal

hexclave exec --cloud-project-id <project-id> "return await hexclaveServerApp.listUsers()"

`hexclave team`

Manage teams. Team operations require a login session. Where a team ID is optional, the CLI can resolve the team interactively or from the available team context.

`hexclave team list`

Synopsis

hexclave team list

Description List the current user’s teams. Options

Option	Description
`--json`	Root option; print teams as JSON.

`hexclave team create`

Synopsis

hexclave team create [options]

Description Create a team. Options

Option	Description
`--display-name <name>`	Team display name.

Behavior and authentication Missing display names prompt interactively and are required in noninteractive environments.

`hexclave team members list`

Synopsis

hexclave team members list [options]

Description List members of a team. Options

Option	Description
`--team-id <id>`	Team ID.
`--json`	Root option; print members as JSON.

`hexclave team members remove`

Synopsis

hexclave team members remove [options]

Description Remove a member from a team. Options

Option	Description
`--team-id <id>`	Team ID.
`--user-id <id>`	Required user ID to remove.
`-y, --yes`	Skip the confirmation prompt.
`--json`	Root option; print the result as JSON.

Behavior and authentication Destructive actions require confirmation interactively and require --yes in noninteractive environments.

`hexclave team invite`

Synopsis

hexclave team invite [options]

Description Invite a user to a team. Options

Option	Description
`--team-id <id>`	Team ID.
`--email <email>`	Email address to invite.
`--json`	Root option; print the result as JSON.

Behavior and authentication Missing email addresses prompt interactively and are required in noninteractive environments.

`hexclave team invitations list`

Synopsis

hexclave team invitations list [options]

Description List invitations sent by a team. Options

Option	Description
`--team-id <id>`	Team ID.
`--json`	Root option; print invitations as JSON.

`hexclave team invitations revoke`

Synopsis

hexclave team invitations revoke [options]

Description Revoke a team invitation. Options

Option	Description
`--team-id <id>`	Team ID.
`--invitation-id <id>`	Required invitation ID.
`-y, --yes`	Skip the confirmation prompt.
`--json`	Root option; print the result as JSON.

Behavior and authentication Destructive actions require confirmation interactively and require --yes in noninteractive environments.

`hexclave team invitations received`

Synopsis

hexclave team invitations received

Description List invitations received by the current user. Options

Option	Description
`--json`	Root option; print invitations as JSON.

`hexclave team invitations accept`

Synopsis

hexclave team invitations accept [options]

Description Accept an invitation received by the current user. Options

Option	Description
`--invitation-id <id>`	Required invitation ID.
`--json`	Root option; print the result as JSON.

`hexclave team leave`

Synopsis

hexclave team leave [options]

Description Leave a team. Options

Option	Description
`--team-id <id>`	Team ID.
`-y, --yes`	Skip the confirmation prompt.
`--json`	Root option; print the result as JSON.

Behavior and authentication Leaving a team is destructive. It requires confirmation interactively and requires --yes in noninteractive environments.

`hexclave team update`

Synopsis

hexclave team update [options]

Description Update a team. Options

Option	Description
`--team-id <id>`	Team ID.
`--display-name <name>`	New team display name.
`--json`	Root option; print the result as JSON.

Behavior and authentication Missing display names prompt interactively and are required in noninteractive environments.

`hexclave team delete`

Synopsis

hexclave team delete [options]

Description Delete a team. Options

Option	Description
`--team-id <id>`	Team ID.
`-y, --yes`	Skip the confirmation prompt.
`--json`	Root option; print the result as JSON.

Behavior and authentication Deleting a team is destructive. It requires confirmation interactively and requires --yes in noninteractive environments.

Getting Started

Going Further

Apps

Integrations

Other

Install and quickstart

Authentication and environment

Command reference

`hexclave init`

`hexclave doctor`

`hexclave fix`

`hexclave logout`

`hexclave whoami`

`hexclave project`

`hexclave project list`

`hexclave project create`

`hexclave config`

`hexclave config pull`

`hexclave config push`

`hexclave dev`

`hexclave deploy`

`hexclave exec`

`hexclave team`

`hexclave team list`

`hexclave team create`

`hexclave team members list`

`hexclave team members remove`

`hexclave team invite`

`hexclave team invitations list`

`hexclave team invitations revoke`

`hexclave team invitations received`

`hexclave team invitations accept`

`hexclave team leave`

`hexclave team update`

`hexclave team delete`

​Install and quickstart

​Authentication and environment

​Command reference

​hexclave init

​hexclave doctor

​hexclave fix

​hexclave login

​hexclave logout

​hexclave whoami

​hexclave project

​hexclave project list

​hexclave project create

​hexclave config

​hexclave config pull

​hexclave config push

​hexclave dev

​hexclave deploy

​hexclave exec

​hexclave team

​hexclave team list

​hexclave team create

​hexclave team members list

​hexclave team members remove

​hexclave team invite

​hexclave team invitations list

​hexclave team invitations revoke

​hexclave team invitations received

​hexclave team invitations accept

​hexclave team leave

​hexclave team update

​hexclave team delete

Install and quickstart

Authentication and environment

Command reference

`hexclave init`

`hexclave doctor`

`hexclave fix`

`hexclave login`

`hexclave logout`

`hexclave whoami`

`hexclave project`

`hexclave project list`

`hexclave project create`

`hexclave config`

`hexclave config pull`

`hexclave config push`

`hexclave dev`

`hexclave deploy`

`hexclave exec`

`hexclave team`

`hexclave team list`

`hexclave team create`

`hexclave team members list`

`hexclave team members remove`

`hexclave team invite`

`hexclave team invitations list`

`hexclave team invitations revoke`

`hexclave team invitations received`

`hexclave team invitations accept`

`hexclave team leave`

`hexclave team update`

`hexclave team delete`