CLI overview
Interact with Hex via the command line.
- Available on the Team and Enterprise plans.
- Requires a personal access token. Admins must enable API access from the Integrations tab in Workspace settings before users can create tokens. See Workspace assets.
- Hex CLI is being actively developed. Commands and configuration are subject to change.
- CLI tool calls do not currently consume Credits. Credit consumption may apply in the future.
The Hex CLI manages Hex projects, cells, runs, data connections, and workspace resources from the command line. This can be used directly or via a local AI agent to automate Hex workflows, create and modify notebook cells, trigger project runs, and inspect workspace state.
Installation
Install the CLI with Homebrew:
brew tap hex-inc/hex-cli
brew trust --tap hex-inc/hex-cli
brew install hex-inc/hex-cli/hex
Alternatively, you can manually install the CLI using the following command:
curl -fsSL https://hex.tech/install.sh | bash
Verify the installation using:
hex --version
The Hex CLI will automatically check for updates and prompt you any time an update is available. Hex CLI releases are hosted on GitHub.
The Hex CLI is currently available for MacOS and Linux users, and is not supported for Windows. Consider using Windows Subsystem for Linux to install the CLI.
Authentication
To get started:
hex auth login
This will open a web browser to select and log into the workspace you wish to use for the CLI. Credentials are stored securely in your system keyring.
If your workspace has a custom URL (such as for single-tenant or EU customers), specify the base URL as part of the login command:
hex auth login -H https://myorganization.hex.tech
You can verify authentication with:
hex auth status
hex projects list
Using the CLI with multiple accounts or workspaces
If you are part of multiple workspaces, you log into each of them separately using the Hex CLI. When logging in, specify a profile name which will be used for each account:
hex auth login workspace1
hex auth login workspace2
hex auth login euworkspace -H https://eu.hex.tech
Switch the currently active account using hex auth switch <profile_name>. The currently active account is global and shared across shell sessions.
Authenticating in CI
In CI, you can run hex auth login with the --token-from-env <env_var> flag and pass in a workspace access token as environment variable.
HEX_API_TOKEN="my-token" hex auth login --token-from-env HEX_API_TOKEN
HEX_API_TOKEN="my-token" hex auth login --token-from-env HEX_API_TOKEN -H https://eu.hex.tech
Usage
The CLI documents itself with the --help flag:
hex --help
# subcommands are also documented using the `--help` flag
hex auth --help
Usage: hex [options] [command]
Commands:
app Manage and run Hex apps
auth Manage authentication with Hex
cell Manage project cells
collection Manage project collections
config Manage CLI configuration
connection Manage data connections
group Manage workspace groups
install Manage additional tools provided by the Hex CLI
project Manage and run Hex projects
run Manage running Hex projects and apps
suggestion Manage context suggestions from the Context Studio
thread Manage Hex agent threads
user Manage workspace users
guide Manage guides
context Manage context
help Print this message or the help of the given subcommand(s)
Options:
-V, --version output the version number
--profile <name> Profile to use (from config) (env: HEX_PROFILE)
--json Output as JSON (for scripting) (default: false)
-q, --quiet Suppress non-essential output (default: false)
-v, --verbose Show verbose output for debugging (default: false)
--no-color Disable colored output
-h, --help Print help
Configuration for AI agents
AI agents that can interact with your command line, such as Claude Code, Cursor, or Codex, can use the hex CLI to create projects, edit cells, and run the Hex Agent.
- Install the general Hex CLI skill with
hex install agent-skill --claude(or--codex/--path <dir>). - To rebuild Tableau or Looker dashboards in Hex, install the Hex migration skills.
Agents that connect to Hex remotely rather than through your command line can create and edit projects through the Hex MCP server instead.
Troubleshooting
Certificate errors behind a corporate VPN or proxy
If hex auth login fails with an error such as SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_VERIFY_LEAF_SIGNATURE, or UNABLE_TO_GET_ISSUER_CERT_LOCALLY, the CLI likely doesn't trust your organization's certificate authority (CA).
Corporate security tools such as Cloudflare WARP inspect HTTPS traffic using certificates signed by your organization's CA. Your browser may trust this CA even when the CLI does not. These are certificate errors, not credential errors.
The Hex CLI includes its own runtime, so updating Node.js on your computer won't fix these errors. The NODE_ variables below still apply, because the CLI's runtime supports them.
There are two ways to fix these errors, depending on how your organization provides its CA.
Use your system's trust store
If the CA is already installed and trusted in your operating system's certificate store, export the NODE_USE_SYSTEM_CA variable before running the CLI:
export NODE_USE_SYSTEM_CA=1
hex auth login
hex auth status
Use a certificate file
If your IT or security team provides a CA certificate file in PEM format, export the NODE_EXTRA_CA_CERTS variable with the file's absolute path before running the CLI:
export NODE_EXTRA_CA_CERTS="/absolute/path/to/company-ca-bundle.pem"
hex auth login
hex auth status
If needed, you can set both NODE_USE_SYSTEM_CA and NODE_EXTRA_CA_CERTS at the same time. Neither setting removes the CLI's default certificates or turns off certificate verification.
If you've already configured your CA for npm using the ca or cafile settings in .npmrc, the Hex CLI doesn't read those settings. Set NODE_EXTRA_CA_CERTS to the same file instead.
These settings only fix certificate errors. If the CLI still can't connect, the cause may be network connectivity, proxy routing, or an IP allowlist. Contact support for help.
Bugs & issues
Please contact support@hex.tech if you encounter any bugs or other issues. Include your CLI version (hex --version) and the full error message.