Hyphen
Log In

Hyphen CLI

A complete reference guide for installing, configuring, and using the Hyphen CLI (hx) to manage applications, environments, and deployments.

Hyphen CLI can be installed in macOS, Windows and Linux environments. In this guide, you will learn how to install and update command-line interface (CLI).

Table of Contents

Installation

sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)"

powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex"

Commands

hyphen

The root command for the Hyphen CLI. For convenience, the alias hx can be used in place of hyphen for all commands.

📘 For convenience, the alias hx can be used in place of hyphen for all commands.

Usage:

hyphen [command]
hx [command]

Core Commands

  • app: Manage applications
  • auth: Authenticate with Hyphen
  • build: Prepare a container or static build for a later deployment
  • deploy: Run a deployment
  • entrypoint: Generate or update the hyphen-entrypoint.sh script
  • env: Manage environments
  • help: List available commands, flags, and their descriptions
  • init: Initialize an app
  • project: Manage projects
  • pull: Retrieve and decrypt environment variables for a specific environment
  • push: Upload and encrypt environment variables for a specific environment
  • set-org: Set the organization ID
  • set-project: Set the project ID
  • update: Update the Hyphen CLI
  • version: Display the version of the Hyphen CLI

Global Flags

  • --organization, -o: Organization ID
  • --project, -p: Project ID
  • --yes, -y: Automatically answer yes for prompts
  • --no: Automatically answer no for prompts

Authentication

Authenticate with Hyphen by entering the hyphen auth command. This will start the OAuth flow (opens a browser window and ask you to sign in with username and password) and save the credentials to your session.

hyphen auth

API Key Authentication

If you are authenticating in a CI/CD environment and need to authenticate using an API key, you can do so in 2 ways:

  1. Use API Key --use-api-key will look for the HYPHEN_API_KEY environment variable first and if not found it will prompt for the key. 
    hx auth --use-api-key
  2. Set API Key --set-api-key VALUE will expect an inline value. The risk in using this method is just in exposing the secret in your terminal output, but it's provided for convenience. 
    hx auth --set-api-key VALUE

Commands

app

Manage applications.

Subcommands

  • create: Create a new application in Hyphen
  • get: Get an app
  • list: List applications in your organization and project

app create

This command allows you to:

  • Create a new application with a specified name
  • Optionally provide a custom app ID or use an automatically generated one
  • Associate the new app with your current organization and project
hyphen app create <app-name> [flags]

Flags

  • -h, --help Help for app create command
  • --id, i: App ID (optional)

app get

This command allows you to:

  • Fetch detailed information about a specific application
  • Use either the application name or ID as the identifier

The command will display various details about the application, including:

  • Project information (ID and name)
  • Application details (name, alternate ID, and ID)
  • Organization information (ID and name)
hyphen app get <app-name or app-id> [flags]

Flags

  • -h, --help Help for app create command

app list

List applications in your organization and project

hyphen app list [flags]

Flags

  • -h, --help Help for app list
  • --page: Page number (default 1)
  • --page-size: Number of results per page (default 10)
  • --table: Display results in a table format

auth

Starts the OAuth flow, opens a browser window for you to sign in with a username and password and saves the credentials to your session.

hyphen auth

build

Prepare a container or static build for a later deployment. The default type, docker, builds an image and uploads it to every ready Container Registry on the project.

With --type static, the command uploads finished website files to every ready Site Registry on the project. Hyphen records one Static build with an artifact for each registry after all uploads succeed. Cloudflare supports static builds.

hx build [flags] [site-directory]

For a static build, run your frontend build command first. Supply its output directory as the final argument. The CLI does not run a frontend build tool or Docker for this type. The directory must contain files; archives and symbolic links are not supported.

Flags

  • --type: Select docker (default) or static.
  • --dockerfile, -f: Set the Dockerfile path for a container build.
  • --env, -e: Associate the build with an environment ID or alternate ID. The default includes all environments.
  • --preview, -r: Associate the build with a preview name.
  • --output json: Return the build result as JSON.
  • --help, -h: Show all build flags.

--dockerfile cannot accompany --type static. A standalone build with --preview does not create or start a preview deployment.

Examples

# Build a container image
hx build

# Upload finished static files
hx build --type static ./dist

# Associate a static build with an environment and preview
hx build --env production --preview "PR 200" --type static ./dist

For more details about the build process, see Builds.

deploy

Deploy a project environment from your local app folder. With no flags, hx deploy selects the environment of type development in the project configured in .hx. Its name and alternate ID may be different from development.

hx deploy [deploymentId] [flags] [site-directory]

Use --env to select an environment by ID or alternate ID within the project linked in .hx. To deploy an app in another project, run from that app's initialized folder. The browser's environment selection does not affect a bare hx deploy.

In the dashboard, select your project's environment, then open the menu beside Deploy → Copy CLI command. The copied command includes --env only when the environment's type isn't development; the organization and project come from your app folder's .hx file.

Run it from the folder initialized with hx init for the app you want to build, and check that its .hx file links to the project shown in the menu.

The CLI prepares the current local app's build, then starts the deployment. Other included apps use uploaded builds. GitHub integration and a Git commit are not required for a local build.

  • Container builds require Docker and at least one ready Container Registry on the project. Container deployments require a ready registry and Cloud Workspace for each target cloud.
  • Static builds require a directory of finished website files and at least one ready Site Registry. Each selected static provider needs a matching artifact. Docker and a Cloud Workspace are not required for static sites.

Hyphen can create missing deployment configuration, but the required connections must be ready. In the dashboard, select Static and the required providers under Deploy to for each static app.

Flags

  • --env: Environment ID or alternate ID; when omitted, selects the environment of type development
  • --type: Select the local build type: docker (default) or static.
  • --sites: Select static apps and optional builds from a list with comma separators.
  • --apps: Select container apps and optional builds from a list with comma separators.
  • --no-build: Use uploaded builds. Static sites do not need a local output directory with this flag.
  • --preview: Preview name; creating a preview also requires --prefix
  • --prefix: Preview host prefix; include it to distinguish previews with the same name
  • --dockerfile, -f: Set the Dockerfile path for a container build.
  • --output json: Return the deployment result as JSON.
  • --help, -h: Show all deployment flags

Examples

# The environment of type development in the configured project
hx deploy

# An environment with alternate ID production in the configured project
hx deploy --env production

# A preview of the configured project's development-type environment
hx deploy --preview "PR 200" --prefix pr200

# Reuse uploaded builds for production
hx deploy --env production --no-build

# Upload finished static files and deploy them to production
hx deploy --env production --type static ./dist

# Deploy a static site preview
hx deploy --preview "PR 200" --prefix pr200 --type static ./dist

# Deploy selected container and static builds
hx deploy --env production --no-build --apps api:latest --sites website:abld_123

Replace ./dist with your frontend output directory. --type static requires this final argument unless you use --no-build. The flag selects the local build type; it does not change an existing deployment member's app type.

Select Apps and Builds

Both --apps and --sites accept app IDs or alternate IDs. Add a colon and a build selector to select an uploaded build:

  • latest: The latest build.
  • lastDeployed: The last deployed build.
  • latestPreview: The latest preview build.
  • abld_...: A specific build ID.

For example, --sites website:latest,docs:lastDeployed selects two static apps. Explicit build selectors use uploaded builds. An entry without a build selector builds the local .hx app when its type matches --type; other entries use latest.

If either selection flag is present, the run includes only the selected apps and sites. Without these flags, the run includes all apps and sites in the deployment. The local app uses its new build unless --no-build applies; other members use latest.

For a local static build, select the local app without a build selector. This example uploads website from the current folder and uses an uploaded container build for api:

hx deploy --env production --type static --apps api:latest --sites website ./dist

The current folder's .hx file must identify website. To use only uploaded builds, select --no-build instead.

Use the current CLI release: hx version checks your installation and hx update updates it. The hyphen executable remains supported; the deployment examples in this section use its hx alias.

Compatibility with existing scripts

A positional deployment ID or alternate ID remains supported for existing scripts. That form selects the deployment directly, so --env does not select its target. Use --env with the project linked in .hx for new commands and automation.

See the Deploy Quickstart for your first local deployment and Deployment Run Methods for automation and dashboard runs.

entrypoint

Generate or update the hyphen-entrypoint.sh script for Docker deployments.

This script is normally created automatically when you run hx init, but this command allows you to:

  • Create the entrypoint script if it's missing (e.g., from having used an older version of hx init)
  • Update the script to the latest version
  • Regenerate the script if it was accidentally deleted or modified
hyphen entrypoint [flags]

Flags

  • --force: Overwrite existing entrypoint file
  • --help, -h: Help for entrypoint command

env

Manage environment .env secrets.

Subcommands

  • list: List environment variables in Hyphen
  • list-versions: List versions of an environment in Hyphen
  • pull: Pull and decrypt environment variables from Hyphen
  • push: Push local environment variables to Hyphen
  • rotate-key: Rotate the encryption key and update all environments
  • run: Run your app with the specified environment

Flags

  • --enivoronment, -e: Project Environment ID (e.g., pevr_12345)
  • -h, --help Help for project list

env list

The env list command displays environment variables stored in Hyphen for your current project.

This command allows you to:

  • View all environments associated with your project
  • See key details about each environment, including ID, version, secret count, size, and publish date
  • Display results in either a detailed list format or a concise table format

The information displayed for each environment includes:

  • ID: The unique identifier for the environment (default for the main environment)
  • Version: The current version number of the environment
  • Secrets Count: The number of secret variables stored in the environment
  • Size: The total size of the environment data
  • Published: The date and time when the environment was last published
hyphen env list [flags]

Flags

  • -h, --help: help for env list
  • --page: Page number (default 1)
  • --page-size: Number of results per page (default 10)
  • --table: Display results in a table format

env list-versions

The env list-versions command displays different versions of a specific environment stored in Hyphen for your current project.

This command allows you to:

  • View all versions of a specific environment
  • See key details about each version, including ID, version number, secret count, size, and publish date
  • Display results in either a detailed list format or a concise table format

The information displayed for each version includes:

  • ID: The unique identifier for the environment
  • Version: The version number of the environment
  • Secrets Count: The number of secret variables stored in this version
  • Size: The total size of the environment data for this version
  • Published: The date and time when this version was published
hyphen env list-versions <environment-id> [flags]

Flags

  • -h, --help: help for env list
  • --page: Page number (default 1)
  • --page-size: Number of results per page (default 10)
  • --table: Display results in a table format

env push

Encrypt and uploads local environment variables to Hyphen.

This command allows you to:

  • Push all environments found in local .env files when no environment is specified
  • Push a specific environment by name
  • Encrypt and securely store your environment variables in Hyphen

The command looks for .env files in the current directory with the naming convention .env.[environment_name].

hyphen env push [flags]

Flags

  • --environment, -e: Specific environment(s) to push to (e.g. development, production, default)
  • --help, -h: Help for push command

env pull

Retrieves environment variables from Hyphen and decrypts them into local .env files.

This command allows you to:

  • Pull a specific environment by name
  • Pull all environments for the application

The pulled environments will be decrypted and saved as .env.[environment_name] files in your current directory.

hyphen env pull [flags]

Flags

  • --environment, -e: Specific environment(s) to pull from (e.g. development, production, default)
  • --force: Force overwrite of locally modified environment files
  • --version: Specify a version to pull
  • --help, -h: Help for pull command

env rotate-key

Rotates the encryption key and updates all environments with the new key.

hyphen env rotate-key [flags]

Flags

  • --force: Force overwrite of locally modified environment files
  • -h, --help: help for env list

env run

Executes your application with the specified environment variables.

hyphen env run [environment] -- [command]

Flags

  • -h, --help: help for `env list

help

List available commands, flags, and their descriptions

hyphen help

init

Initialize an app, which creates the .hx, .hxkey, and hyphen-entrypoint.sh files

The hyphen-entrypoint.sh script is designed for use in Docker containers and automates the process of downloading the Hyphen CLI, authenticating with an API key, pulling environment variables, and running your application with those variables loaded.

Note: If the hyphen-entrypoint.sh is missing (e.g. because you ran init with an older version of hx) or needs to be updated, you can re-create it with hx entrypoint (and use --force if needed to overwrite it).

hyphen init <app-name> [flags]

Flags

  • --id, i: APP ID (optional)
  • --help, -h: Help for init command

Examples

hyphen init
hyphen init "My New App"
hyphen init "My New App" --id my-custom-app-id

project

Manage projects within your organization.

Subcommands

  • create: Create a new project
  • get: Get a project
  • list: List projects in your organization

project create

This command allows you to:

  • Create a new project with a specified name
  • Automatically generate an alternate ID based on the project name

The project name:

  • Can include spaces and special characters
  • Will be trimmed of leading/trailing spaces and quotes

The alternate ID:

  • Is automatically generated from the project name
  • Contains only alphanumeric characters and hyphens
  • Replaces spaces with hyphens and removes other special characters

After creation, you'll receive a summary of the new project, including its:

  • Name
  • ID (assigned by Hyphen)
  • Alternate ID (generated from the name)
hyphen project create <project-name> [flags]

Flags

  • -h, --help Help for project create command

project get

This command allows you to:

  • Fetch detailed information about a specific project
  • Use either the project name or ID as the identifier

The command will display the following details about the project:

  • Name: The project's full name
  • ID: The unique identifier assigned by Hyphen
  • AlternateID: The human-readable identifier generated from the project name
hyphen project get <project-name or project-id> [flags]

Flags

  • -h, --help Help for project get command

project list

This command allows you to:

  • View all projects in your current organization
  • See key details of each project at a glance

For each project, the command will display:

  • Name: The project's full name
  • ID: The unique identifier assigned by Hyphen
  • AlternateID: The human-readable identifier generated from the project name

If no projects are found in your organization, you'll be informed accordingly.

The projects are displayed in a list format, with each project's details separated by an empty line for better readability.

Note: The list is fetched based on your current organization context. Ensure you're in the correct organization before running this command.

hyphen project list [flags]

Flags

  • -h, --help Help for project list

pull

Retrieves environment variables from Hyphen and decrypts them into local .env files.

This command allows you to:

  • Pull a specific environment by name
  • Pull all environments for the application

The pulled environments will be decrypted and saved as .env.[environment_name] files in your current directory.

hyphen pull [flags]

Flags

  • --environment, -e: Specific environment(s) to pull from (e.g. development, production, default)
  • --force: Force overwrite of locally modified environment files
  • --version: Specify a version to pull
  • --help, -h: Help for pull command

push

Encrypt and uploads local environment variables to Hyphen.

This command allows you to:

  • Push all environments found in local .env files when no environment is specified
  • Push a specific environment by name
  • Encrypt and securely store your environment variables in Hyphen

The command looks for .env files in the current directory with the naming convention .env.[environment_name].

hyphen push [flags]

Flags

  • --environment, -e: Specific environment(s) to push to (e.g. development, production, default)
  • --help, -h: Help for push command

set-org

Set the organization ID in .hx.

hyphen set-org <id>

Flags

  • --global: Set the org ID globally
  • --help, -h: Help for set-org command

set-project

Set the project ID in .hx.

hyphen set-project <id>

Flags

  • --global: Set the project ID globally
  • --help, -h: Help for set-project command

update

Use update to get the latest version of the Hyphen CLI

hyphen update

version

Display the current version of the Hyphen CLI

hyphen version