CLI

The Hubfly CLI is the local-first way to deploy apps, manage repeatable build configuration, automate deployments from scripts, and open private HubTunnels without doing everything through the dashboard.

Use the CLI when you want the speed of your terminal with the operational model of Hubfly Space: projects, regions, containers, runtime resources, persistent storage, environment variables, public endpoints, private tunnels, and deployment history.

What the CLI is for

The CLI covers four main workflows:

The CLI does not replace the full dashboard. It gives you a terminal-native path for the operations that are naturally local: building from a directory, deploying from a config file, and forwarding private ports to your laptop.

Install

Install the CLI globally with npm:

npm install -g hubfly-cli

Verify it is available:

hubfly --help

Recommended prerequisites:

• Node.js and npm available on your machine
• A Hubfly account
• Access to the target project
• Docker support or local build support expected by the CLI builder workflow
• Network access to Hubfly and the target region upload endpoint

Authenticate

The CLI uses a browser-based authentication flow and creates a personal access token for the CLI session.

hubfly login

The profile area also exposes CLI access management so you can review CLI tokens from your account settings.

Deploy From Your Machine

hubfly deploy is the main local deployment command.

When you run it from a project directory, the CLI prepares a deploy plan, builds the app locally, uploads the resulting image to the selected Hubfly region, and asks Hubfly to create or replace a container using the deployment config.

Typical command:

hubfly deploy

Advanced/config-first path:

hubfly deploy advanced

Non-interactive example:

hubfly deploy \
  --project proj_123 \
  --region eu-west-1 \
  --config ./hubfly.build.json \
  --yes

How CLI deploy works

A CLI deploy follows this high-level flow:

1. The CLI loads or creates hubfly.build.json.
2. It resolves the target project, region, container name, runtime settings, ports, env vars, and deployment mode.
3. It uses a local Hubfly Builder version to build the image from your machine.
4. It creates a deploy session in Hubfly.
5. Hubfly returns a regional image upload endpoint and a one-time upload token.
6. The CLI uploads the built image to the region.
7. Hubfly records the uploaded image as a Hubfly-owned project image.
8. Hubfly deploys the image as a new container or swaps it into the bound container.
9. The project build/deployment history updates with the CLI build result.

This is why CLI deploys are fast for local iteration but still visible in Hubfly operations.

CLI deploy sessions

Behind the scenes, a CLI deploy creates a build session with metadata such as:

Upload tokens are checked when the build callback arrives. This prevents a random upload from being attached to the wrong CLI build session.

Bound container redeploys

The CLI stores the target container in hubfly.build.json after the first successful deploy. On the next deploy, Hubfly uses that binding to replace the same logical container instead of creating a brand-new service every time.

This behavior is important for production because it preserves the operational surface around the service:

• Same container identity where possible
• Same public endpoint intent
• Same project placement
• Cleaner build history
• Fewer duplicate services after repeated local deploys

If the bound container no longer exists, the CLI can clear the stale binding and continue by creating a new container.

Build Config File

The CLI stores deployment intent in hubfly.build.json.

This file is the bridge between local development and Hubfly operations. It tells the CLI what to build and tells Hubfly how the result should run.

It can include:

• Project ID, project name, and region
• Bound container ID and container name
• Build mode, working directory, context directory, and Dockerfile path
• Deployment tier and resources
• Runtime behavior such as auto-sleep, always-on, and scaling flags
• Ports and protocols
• Environment variables and scopes
• Volume definitions
• Builder metadata from previous deploys

Example:

{
  "version": 1,
  "project": {
    "id": "proj_123",
    "name": "edge-api",
    "region": "eu-west-1"
  },
  "container": {
    "id": "cont_456",
    "name": "api"
  },
  "build": {
    "mode": "auto",
    "workingDir": ".",
    "contextDir": "."
  },
  "deploy": {
    "tier": "dedicated",
    "resources": {
      "cpu": 1,
      "ram": 800,
      "storage": 1
    },
    "runtime": {
      "autoSleep": false,
      "autoScale": false,
      "is24x7": true
    },
    "ports": [
      {
        "container": 3000,
        "protocol": "TCP"
      }
    ]
  },
  "env": [
    {
      "name": "NODE_ENV",
      "value": "production",
      "scope": "runtime"
    }
  ]
}

Build Config Helpers

These commands work with the same hubfly.build.json file used by hubfly deploy.

hubfly build init
hubfly build validate
hubfly build edit
hubfly build explain

A good production workflow is to keep hubfly.build.json in version control when it describes stable deployment behavior, while keeping secrets out of it.

Build modes

The CLI can build from automatic detection or from an explicit Dockerfile.

Dockerfile support

If your project already has a Dockerfile, the CLI can use it directly. This is often the best option for teams that already build containers in CI or need precise runtime control.

Example Dockerfile config:

{
  "build": {
    "mode": "dockerfile",
    "dockerfilePath": "./deploy/Dockerfile"
  }
}

Use Dockerfile mode when you need:

• OS packages
• Multi-stage builds
• Custom system dependencies
• Exact runtime entrypoints
• Reproducible local/CI/prod images
• Framework behavior the auto-detection path should not guess

Runtime configuration

A CLI deploy does more than upload an image. The deploy config also tells Hubfly how to run the container.

Important runtime decisions include:

For production, do not treat these as defaults to skip. Review them like infrastructure configuration.

Environment variables

Environment variables in CLI config should be intentional.

Use them for:

• Runtime modes such as NODE_ENV=production
• API URLs
• Feature flags
• Database connection strings
• Service tokens
• Build-time settings when required

Avoid:

• Committing real production secrets to Git
• Mixing build-time and runtime variables accidentally
• Depending on local .env files that CI will not have
• Changing env vars without redeploying when the app reads them only at startup

Use Hubfly dashboard/project secret management patterns for sensitive production values when that is safer for your team.

Non-Interactive And CI

The CLI supports scriptable deploys for CI, automation, and headless environments.

Common flags:

Example CI deploy:

hubfly deploy \
  --project proj_123 \
  --region eu-west-1 \
  --config ./hubfly.build.json \
  --builder-version v1.7.1 \
  --yes

Use --yes only when the config has already been reviewed. CI should not be discovering production deployment settings for the first time.

CI/CD recommendations

For reliable CI deploys:

1. Commit hubfly.build.json if it represents stable deploy intent.
2. Store CLI tokens in CI secrets, not in the repository.
3. Pin the builder version for repeatability when needed.
4. Use a fixed project and region in CI.
5. Avoid interactive prompts with --yes only after config validation.
6. Use --detach when the pipeline should hand off deployment monitoring to Hubfly.
7. Check the project build history after deployment.
8. Keep production env vars controlled outside the pipeline when they are sensitive.

A CI pipeline should not silently create a new production service every run unless that is intentional. Use bound container behavior for normal redeploys.

Local deploy vs Git deploy

Hubfly supports both local CLI deploys and Git-based deploys.

A common team pattern is to use CLI deploys for development and Git deploys or image deploy hooks for production.

CLI builds in project history

CLI deploys appear in the project build history as CLI-originated builds.

Operational notes:

• CLI builds are marked as local image upload deployments.
• The builder version can appear in the build details.
• Uploaded images are tracked as Hubfly-owned project images.
• CLI-originated builds may not keep the same remote builder logs as Git builds because the build happened on your machine.
• Re-running the CLI deploy normally targets the bound container from the config.

This gives teams visibility into deploys without pretending local builds are the same as remote Git builds.

Create A Tunnel

HubTunnels are the CLI path for private access to containers.

Use tunnels when the service should stay internal and you only need temporary local access for a database, admin panel, private API, or debugging endpoint.

Common commands:

hubfly tunnel create --project <project_id>
hubfly tunnel create --project <project_id> --container <container_id> --port 5432 --local 5432
hubfly tunnel create --project <project_id> --container <container_id> --port 8080 --local 3000

Database example:

hubfly tunnel create --project <project_id> --container <postgres_container_id> --port 5432 --local 15432
psql -h localhost -p 15432 -U postgres postgres

Private HTTP example:

hubfly tunnel create --project <project_id> --container <admin_container_id> --port 8080 --local 8080

Then open:

http://localhost:8080

List And Stop Tunnels

hubfly tunnel list
hubfly tunnel stop <tunnel_id>

Tunnels are temporary and should be stopped after the maintenance or debugging session is complete.

See HubTunnels for the full private access model.

Security best practices

Follow these practices when using the CLI:

• Treat CLI tokens like production credentials.
• Do not commit tokens, .env files, or private tunnel keys.
• Use least-privilege project access for team members running CLI deploys.
• Review hubfly.build.json before using --yes in automation.
• Keep production secrets in controlled secret storage.
• Prefer HubTunnels over public endpoints for databases and admin tools.
• Stop tunnels when you finish using them.
• Pin builder versions when deterministic deploys matter.
• Avoid deploying from a dirty local tree unless you deliberately want local-only changes in the image.

Troubleshooting

Production checklist

Before using the CLI for production deploys, verify:

• hubfly.build.json is reviewed and reproducible.
• The target project and region are correct.
• The bound container behavior is intentional.
• Runtime resources match expected load.
• The exposed port is correct.
• Persistent paths use volumes.
• Secrets are not committed.
• CI uses a secure CLI token.
• Public services have domains, SSL, and Firewall where needed.
• Private services use HubTunnels instead of public ports.
• Build/deployment history is monitored after deploy.

FAQ

Does hubfly deploy build remotely or locally?

The CLI deploy flow builds on your machine with the Hubfly Builder, uploads the resulting image to the selected region, and then Hubfly deploys that image.

Do CLI deploys show in Hubfly?

Yes. CLI deploys appear in project build history as CLI/local image upload deployments, and uploaded images are tracked as project images.

Should I commit hubfly.build.json?

Commit it when it represents shared deployment intent. Do not commit secrets or machine-specific temporary values.

What happens on the second CLI deploy?

The CLI uses the bound container stored in the config so the deploy replaces the same logical service instead of creating duplicates.

Can I use the CLI in CI?

Yes. Use non-interactive flags such as --project, --region, --config, and --yes, and store the CLI token in CI secrets.

Should I use CLI deploy or Git deploy for production?

Use CLI deploy when local builds are part of your workflow. Use Git deploy when production should build from repository state. Many teams use CLI for development and Git or image deploy hooks for production.

Can the CLI access private databases?

Yes, through HubTunnels. Create a tunnel to the database container and connect using a local client against localhost:<local_port>.

Related docs

• Quick Start
• Deploy From Git
• Docker Image Reference
• HubTunnels
• Platform
• Architecture