Guides

Hyphen CLI

Work seamlessly with Hyphen from the command line

Suggest Edits

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

  • auth: Authenticate with Hyphen
  • update: Update the Hyphen CLI
  • init: Initialize an app
  • set-org: Set the organization ID
  • set-project: Set the project ID
  • version: Display the version of the Hyphen CLI
  • push: Upload and encrypt environment variables for a specific environment
  • pull: Retrieve and decrypt environment variables for a specific environment
  • link: Shorten a URL and optionally generate a QR code
  • app: Manage applications
  • project: Manage projects
  • env: Manage environments
  • help: List available commands, flags, and their descriptions

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:

  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. 
    hyphen 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. 
    hyphen auth --set-api-key VALUE

Commands

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

update

Use update to get the latest version of the Hyphen CLI

hyphen update

init

Initialize an app, which creates the .hx and .hxkey files

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

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

version

Display the current version of the Hyphen CLI

hyphen version

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

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

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

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

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

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

Updated 22 days ago