Hyphen CLI

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).

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 convience, 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: Build and upload a Docker image without deploying
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
link: Shorten a URL and optionally generate a QR code
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

--org: Organization ID (e.g., org_123)
--proj: Project ID (e.g., proj_123)
--env: Environment ID (e.g., env_12345)
--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:

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.
```
hyphen auth -- use-api-key
```
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.
```
hyphen 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`

Build and upload a Docker image to your project's container registry without deploying it.

This command is useful for:

Testing your build process without triggering a deployment
Pre-building artifacts that can be deployed later
Verifying your Dockerfile and container registry configuration

The build command performs the same build process as hx deploy, but stops after uploading the image to your container registry.

hyphen build [flags]

Flags

--help, -h: Help for build command

Examples

hyphen build
hx build

For more details about the build process, see Builds.

`deploy`

Run a deployment by executing a deployment policy.

This command builds your Docker image (unless --no-build is specified), pushes it to your container registry, and deploys your application according to the deployment policy configuration.

hyphen deploy <deployment-policy-name-or-id> [flags]

Flags

--no-build: Skip the build step and use the most recent build
--help, -h: Help for deploy command

Examples

hyphen deploy my-deployment-policy
hyphen deploy dpol_123456789
hx deploy production --no-build

For more information about deployments, see Deployment Run Methods.

`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

`link`

Shorten a URL and optionally generate a QR code.

hyphen link <long_url> [flags]

Flags

--code: Custom short code
--domain: The domain to use when shortening
--qr: Generate a QR code
--tag: Tag the shortened URL.
--title: The title for the shortened URL
--help, -h: Help for link command

`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 app 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

Installation

Commands

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

Core Commands

Global Flags

Authentication

API Key Authentication

Commands

app

Subcommands

app create

Flags

app get

Flags

app list

Flags

auth

build

Flags

Examples

deploy

Flags

Examples

entrypoint

Flags

env

Subcommands

Flags

env list

Flags

env list-versions

Flags

env push

Flags

env pull

Flags

env rotate-key

Flags

env run

Flags

help

init

Flags

Examples

link

Flags

project

Subcommands

project create

Flags

project get

Flags

project list

Flags

pull

Flags

push

Flags

set-org

Flags

set-project

Flags

update

version

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

`app`

`app create`

`app get`

`app list`

`auth`

`build`

`deploy`

`entrypoint`

`env`

`env list`

`env list-versions`

`env push`

`env pull`

`env rotate-key`

`env run`

`help`

`init`

`link`

`project`

`project create`

`project get`

`project list`

`pull`

`push`

`set-org`

`set-project`

`update`

`version`