Last updated on 5th November 2026

Configuring Build Pipelines via CLI

The DeployHQ CLI lets you configure every aspect of your build pipeline, including build commands, configurations, config files, environment variables, SSH commands, and excluded files.

Build Commands

Build commands run during the build phase of a deployment (e.g., npm install, npm run build).

# List build commands
dhq build-commands list -p my-app

# Create a build command
dhq build-commands create -p my-app --command "npm install" --description "Install dependencies"

# Update a build command
dhq build-commands update <id> -p my-app --command "npm ci"

# Delete a build command
dhq build-commands delete <id> -p my-app

Build Configurations

Build configurations control the runtime environment for your builds, including language versions and packages.

# List build configurations
dhq build-configs list -p my-app

# Show a specific build configuration
dhq build-configs show <id> -p my-app

# Show the default build configuration
dhq build-configs default -p my-app

# Create a build configuration
dhq build-configs create -p my-app --packages '{"node":"18"}'

# Update a build configuration
dhq build-configs update <id> -p my-app --packages '{"node":"20","ruby":"3.2"}'

# Delete a build configuration
dhq build-configs delete <id> -p my-app

Setting a Language Version

Set the version of a language used on the build server:

dhq build-languages set node --version 20 -p my-app

To change the version for a specific build configuration override, pass its ID with --build-config:

dhq build-languages set node --version 20 --build-config <build-config-id> -p my-app

Language Versions

View available language versions for the build server:

dhq language-versions list

This shows all supported versions for Node.js, Ruby, PHP, Python, Go, and other languages available on the DeployHQ build server.

Build Cache Files

Build cache files are file or directory patterns the build server caches between deployments, such as node_modules or vendor/. Cached paths are restored at the start of each build, which cuts the time spent reinstalling dependencies.

# List build cache files
dhq build-cache-files list -p my-app

# Add a path to the build cache
dhq build-cache-files create -p my-app --path "node_modules"

# Change a cached path
dhq build-cache-files update <id> -p my-app --path "vendor/"

# Remove a path from the cache
dhq build-cache-files delete <id> -p my-app

To skip the cache for a single deployment, run dhq deployments create with --use-cache=false.

Build Known Hosts

Build known hosts are SSH host keys the build server should trust. Add one when your build commands fetch from a private Git host (such as a self-hosted GitLab or Gitea), so the build does not fail waiting for host-key confirmation.

# List build known hosts
dhq build-known-hosts list -p my-app

# Add a known host
dhq build-known-hosts create -p my-app \
  --hostname git.example.com \
  --public-key "ssh-ed25519 AAAA..."

# Remove a known host
dhq build-known-hosts delete <id> -p my-app

Config Files

Config files are deployed alongside your code but are not stored in your repository. They are commonly used for environment-specific configuration (e.g., config/database.yml, .env).

# List config files
dhq config-files list -p my-app

# Show a config file (including contents)
dhq config-files show <id> -p my-app

# Create a config file
dhq config-files create -p my-app --path ".env" --body "DATABASE_URL=postgres://localhost/mydb"

# Update a config file
dhq config-files update <id> -p my-app --body "DATABASE_URL=postgres://prod/mydb"

# Delete a config file
dhq config-files delete <id> -p my-app

Targeting Servers

By default, a config file is uploaded to all servers in the project, including servers you add later. Use --server to limit it to specific servers or server groups. You can pass names or identifiers, and repeat the flag or separate values with commas.

# Only upload to one server
dhq config-files create -p my-app --path ".env" --body "APP_ENV=production" --server production

# Target several servers
dhq config-files update <id> -p my-app --server production,staging

If a name does not match a server or server group, the command fails and lists the valid choices. When you update a config file without --server or --all-servers, its server targeting is left unchanged. To make an existing file apply to every server again, use --all-servers:

dhq config-files update <id> -p my-app --all-servers

Build-Only Config Files

Use --build-only for a file that is only available to your build commands and is never uploaded to a server. This suits package-manager credentials such as an .npmrc.

dhq config-files create -p my-app \
  --path ".npmrc" \
  --body "//registry.npmjs.org/:_authToken=<your-token>" \
  --build-only

Global Config Files

Global config files are account-wide files you edit once and attach to any project.

# List global config files
dhq global-config-files list

# Show a global config file
dhq global-config-files show <id>

# Create a global config file
dhq global-config-files create --name "monitoring.conf" --body "<file contents>"

# Update a global config file
dhq global-config-files update <id> --body "<new contents>"

# Delete a global config file
dhq global-config-files delete <id>

Link a global config file into a project, or remove the link:

dhq config-files link-global <config-file-id> -p my-app
dhq config-files unlink-global <config-file-id> -p my-app

Environment Variables

Project-level environment variables are available during builds and deployments.

# List environment variables
dhq env-vars list -p my-app

# Show a specific variable
dhq env-vars show DATABASE_URL -p my-app

# Create an environment variable
dhq env-vars create -p my-app --name DATABASE_URL --value "postgres://localhost/mydb"

# Update an environment variable
dhq env-vars update <id> -p my-app --value "postgres://prod/mydb"

# Delete an environment variable
dhq env-vars delete <id> -p my-app

Locked Variables

Add --locked to hide the value after it is saved. Locked values are write-only, which makes them suitable for secrets. If you omit --value, the CLI prompts for it securely.

dhq env-vars create -p my-app --name SECRET_KEY --locked
dhq env-vars update <id> -p my-app --locked

Global Environment Variables

Account-wide environment variables are available to all projects.

# List global environment variables
dhq global-env-vars list

# Show a global variable
dhq global-env-vars show <id>

# Create a global variable
dhq global-env-vars create --name DEPLOY_TOKEN --value "secret-token"

# Create a locked global variable (value hidden after creation)
dhq global-env-vars create --name REGISTRY_TOKEN --locked

# Update a global variable
dhq global-env-vars update <id> --value "new-token"

# Delete a global variable
dhq global-env-vars delete <id>

A project-level variable with the same name overrides the global variable for that project.

SSH Commands

SSH commands run on the server before or after file transfer during deployment.

# List SSH commands
dhq ssh-commands list -p my-app

# Show an SSH command
dhq ssh-commands show <id> -p my-app

# Create an SSH command (runs on all servers by default)
dhq ssh-commands create -p my-app --command "sudo systemctl restart app"

# Run only on a server's first deployment (for example, one-time setup)
dhq ssh-commands create -p my-app --command "php artisan storage:link" --timing first

# Update an SSH command
dhq ssh-commands update <id> -p my-app --command "sudo systemctl reload app"

# Delete an SSH command
dhq ssh-commands delete <id> -p my-app

The --timing flag accepts all (the default), first, or after_first. Timing is based on each server's own deployment history: first runs only on the first deployment to a server (so it runs once on every newly added server, and never again on that server), and after_first runs on every deployment after that. It does not mean the first server in a deployment.

Targeting Servers

SSH commands run on all servers in the project that support SSH, including servers added later. Use --server (repeatable or comma-separated, by name or identifier) to limit a command to specific servers or server groups, and --all-servers on update to apply it everywhere again. Without either flag, an update leaves the targeting unchanged.

dhq ssh-commands create -p my-app --command "sudo systemctl restart app" --server production
dhq ssh-commands update <id> -p my-app --all-servers

Global SSH Commands

To reuse an account-wide SSH command in a project, link it, or remove the link:

dhq ssh-commands link-global <command-id> -p my-app
dhq ssh-commands unlink-global <command-id> -p my-app

Excluded Files

Excluded file patterns prevent certain files from being deployed to the server.

# List excluded files
dhq excluded-files list -p my-app

# Show an excluded file pattern
dhq excluded-files show <id> -p my-app

# Create an exclusion pattern
dhq excluded-files create -p my-app --path "node_modules"
dhq excluded-files create -p my-app --path ".git"
dhq excluded-files create -p my-app --path "tests/"

# Update an exclusion pattern
dhq excluded-files update <id> -p my-app --path "test/"

# Delete an exclusion pattern
dhq excluded-files delete <id> -p my-app

By default an exclusion applies to all servers in the project, including servers added later. To limit it, use --server (repeatable or comma-separated, by name or identifier). Use --all-servers on update to make an existing rule apply everywhere. Without either flag, an update leaves the targeting unchanged.

# Only skip the file on one server
dhq excluded-files create -p my-app --path "deploy.sh" --server production

# Make an existing rule apply to every server
dhq excluded-files update <id> -p my-app --all-servers