Hubfly spaceDocs
Console

Hubfly space CLI Quick Start

The hubfly CLI is the fastest way to deploy code, inspect projects, open private tunnels, stream logs, run shell commands, create and operate Managed Databases, Object Storage and Realtime servers, read Web Analytics, and automate Hubfly space from CI.

Deploy with your coding agent

Install the portable Hubfly space CLI skill to give Codex, Claude Code, Cursor, and other compatible agents a safe inspect, approve, deploy, and verify workflow.

Install The CLI

On Linux and macOS, install the latest release with the shell installer:

terminal

$ curl -fsSL https://raw.githubusercontent.com/hubfly-space/hubfly-cli/main/install.sh | bash
$ hubfly version

The installer downloads the right release archive from GitHub for your OS and CPU, then installs hubfly to /usr/local/bin or ~/.local/bin if the system path is not writable.

PlatformInstall PathNotes
Linuxcurl ... | bashSupports amd64 and arm64.
macOScurl ... | bashSupports Intel and Apple Silicon.
WindowsManual release downloadDownload the hubfly_windows_*.zip asset from GitHub releases and add it to PATH.
Source buildgo build -o hubfly .Use this when developing the CLI locally.

PATH check

If install succeeds but hubfly version is not found, add ~/.local/bin to your shell PATH and open a new terminal.

First Deploy

Start from an app directory that has a Dockerfile or a framework the Hubfly space builder can detect. Then log in and deploy.

1. Log in

terminal

$ hubfly login
Please authenticate to continue. Go to https://dashboard.hubfly.space/cli/auth to get the token
Enter your API token: hf_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

2. Deploy from the current folder

terminal

$ cd my-app
$ hubfly deploy

3. Use a non-interactive deploy when scripting

terminal

$ hubfly deploy --project my-api --region eu-1 --yes
$ hubfly deploy --project new --region rw-kigali-1 --yes

hubfly deploy creates or reuses hubfly.build.json, checks the latest hubfly-builder release unless you pin one, builds a local Docker image, uploads it to the target region, shows a diff, and waits for the deployment unless --detach is set.

Daily Commands

GoalCommand
Check the signed-in userhubfly whoami
Open the project/container terminal UIhubfly projects
Deploy the current apphubfly deploy
Deploy with a Dockerfilehubfly deploy --dockerfile ./deploy/Dockerfile --yes
Follow container logshubfly logs web-app --follow
Run one command in a containerhubfly exec web-app -- printenv
Open a shellhubfly ssh web-app
Forward a private databasehubfly tunnel postgres-db 5432 5432
Create a PostgreSQL database and connect an apphubfly db create app-db --engine postgresql --project new, then hubfly db bind app-db --to web
Open a SQL client on a managed databasehubfly db connect app-db
Upload a file to Object Storagehubfly storage put ./logo.png project-assets/images/
Watch live Realtime traffichubfly rt tail chat
See who is on your website nowhubfly analytics realtime app.example.com --watch
See what a stream server has livehubfly stream live acme-tv
Check for a CLI updatehubfly update --check

Command Groups

Every group prints its full usage with hubfly <group> help. The reference pages list each command with its flags and examples.

GroupUse it toReference
hubfly login, logout, whoamiSign in with a personal access token and check the account.Authentication
hubfly deploy, hubfly buildBuild the current folder and deploy it to a Cell project.Deploy, Build config
hubfly stackDeploy a Docker Compose file as a group of services.Stack
hubfly tunnel, ssh, exec, logsReach private ports, open shells, run commands and follow logs.Tunnels & exec
hubfly dbCreate, connect to, query and operate managed PostgreSQL, MySQL and SQLite (libSQL).Managed Databases
hubfly storageManage Storage projects, buckets, objects, S3 access keys, assets and video.Object Storage
hubfly realtime (rt)Run Pusher-compatible WebSocket servers: apps, keys, bindings, publishing, live tail and webhooks.Realtime
hubfly analyticsAdd Web Analytics sites, print install snippets, read stats and realtime visitors, export data and manage ingest keys.Web Analytics
hubfly stream (live)Run live video servers: inputs and keys, channels, restream destinations, scenes, schedules, live status, push and play.Managed Streams
hubfly projectsBrowse projects, containers, metrics and tunnels in a terminal UI.Terminal UI
hubfly service, updateRun the local tunnel daemon and update the CLI.Service & updates

Use In CI

In CI, create a Dashboard personal access token and store it as a secret named HUBFLY_TOKEN. Use --yes so the deploy can run without prompts.

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Hubfly space CLI
        run: curl -fsSL https://raw.githubusercontent.com/hubfly-space/hubfly-cli/main/install.sh | bash
      - name: Deploy
        env:
          HUBFLY_TOKEN: ${{ secrets.HUBFLY_TOKEN }}
        run: hubfly deploy --project my-api --region eu-1 --yes --detach

Filter every CLI command, flag, and example from one place.

Showing 58 commands
hubfly loginauth
Docs

Authenticate CLI session interactively via browser or headless personal access token.

Flags & Options

--tokenPersonal access token string for headless / non-interactive CLI authentication
$ hubfly login --token hf_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
hubfly logoutauth
Docs

Invalidate local CLI auth session and clear stored tokens from ~/.hubfly/config.json.

$ hubfly logout
hubfly whoamiauth
Docs

Display currently authenticated account user name, email, and organization binding.

$ hubfly whoami
hubfly projectstui
Docs

Launch persistent Bubble Tea terminal UI to browse projects, containers, metrics, and tunnels.

Flags & Options

--orgFilter project workspace list by organization ID or slug
$ hubfly projects --org org_prod_123
hubfly deploydeploy
Docs

Build working directory locally, upload image to regional builder, and update bound container.

Flags & Options

--project <id|name|new>Target existing project ID/name or create a new project
--region <region>Target deployment region (required for non-interactive new project deploys)
--yesSkip interactive confirmation prompts and diff confirmation
--config <path>Custom path to hubfly.build.json or project workspace directory
--detachReturn immediately after upload without waiting for container healthcheck
--dockerfile <path>Force Dockerfile mode and override default Dockerfile location
--builder-version <tag>Pin specific hubfly-builder release tag (e.g. v1.7.1)
$ hubfly deploy --project edge-api --region eu-west-1 --yes --detach
hubfly build initconfig
Docs

Initialize or refresh local hubfly.build.json configuration file with project defaults.

Flags & Options

--forceOverwrite existing build configuration file with defaults
--printPrint generated JSON structure directly to stdout
$ hubfly build init --dockerfile ./deploy/Dockerfile
hubfly build validateconfig
Docs

Verify local build configuration file and inspect build source validity before deployment.

Flags & Options

--jsonOutput structured validation response in JSON format for CI
$ hubfly build validate --json
hubfly build explainconfig
Docs

Inspect what hubfly-builder auto-detects and explain generated Dockerfile/run steps.

Flags & Options

--jsonOutput detection report as JSON
$ hubfly build explain --json
hubfly stack planstack
Docs

Inspect local Compose file and preview changes, resources, ports, and volumes.

Flags & Options

--file <path>Custom Compose file path (defaults to docker-compose.yml)
--jsonOutput machine-readable stack summary in JSON format
$ hubfly stack plan --file docker-compose.prod.yml
hubfly stack upstack
Docs

Deploy Compose stack services to Hubfly space cloud with dependency ordering and volume creation.

Flags & Options

--project <id|name|new>Target Hubfly space project for stack allocation
--region <region>Target deployment region
--yesSkip interactive prompts
--remove-orphansRemove managed containers no longer present in Compose file
--no-buildSkip local Docker builds for build-backed services
$ hubfly stack up --project ecommerce-stack --region eu-west-1 --yes
hubfly stack statusstack
Docs

Show live runtime status for all services declared in local stack state.

$ hubfly stack status
hubfly stack logsstack
Docs

Stream combined stdout and stderr logs for all or selected stack services.

Flags & Options

-f, --followContinuously tail live stack logs
$ hubfly stack logs api db -f
hubfly stack downstack
Docs

Tear down stack services in reverse dependency order.

Flags & Options

--volumesDelete associated stack persistent storage volumes
$ hubfly stack down --volumes --yes
hubfly tunneltunnels
Docs

Establish encrypted Yamux WebSocket tunnel from localhost port to private container port.

$ hubfly tunnel postgres-db 5432 5432
hubfly sshtunnels
Docs

Open interactive PTY shell session or run non-interactive command inside container.

$ hubfly ssh api-server -- ls -la /app/data
hubfly exectunnels
Docs

Execute single command with 55s timeout inside target container.

$ hubfly exec web-app -- printenv
hubfly logstunnels
Docs

Stream real-time container log output directly to local terminal.

Flags & Options

-f, --followKeep log connection open and stream new lines
$ hubfly logs web-app -f
hubfly db createdatabases
Docs

Create a managed PostgreSQL, MySQL or SQLite (libSQL) database after quoting its monthly price, then wait until it is ready.

Flags & Options

--enginepostgresql (default), mysql or libsql
--version <v>Engine version, such as 17 or 9.7
--size <preset>nano, small, medium, large or xlarge; or --cpu and --memory
--storage <gib>1-500 GiB, default 10; can grow but never shrink
--project <id|name|new>Managed project to create it in, or new
--yesAccept the quoted price without a prompt
$ hubfly db create app-db --engine postgresql --size nano --project new
hubfly db connectdatabases
Docs

Start psql or mysql on your machine with TLS required; checks the IP allowlist first. The password never appears on the command line.

$ hubfly db connect app-db -- -c 'select version()'
hubfly db urldatabases
Docs

Print the connection URL with its TLS parameter. The password stays masked unless --reveal, which is audited.

Flags & Options

--revealInclude the password (recorded in the activity log)
$ hubfly db url app-db --reveal
hubfly db querydatabases
Docs

Run SQL through Hubfly space without a local client. Read-only unless --write.

Flags & Options

--writeAllow statements that change data or schema
--formattable (default), json or csv
$ hubfly db query app-db 'select count(*) from users'
hubfly db binddatabases
Docs

Write DATABASE_URL, or LIBSQL_URL and LIBSQL_AUTH_TOKEN, into a Cell project's environment.

Flags & Options

--to <project>Cell project that receives the variables
--new-userCreate a dedicated database user for the app
$ hubfly db bind app-db --to web
hubfly db network allowdatabases
Docs

Add an IP address or CIDR range to the database's allowlist (up to 64 entries).

Flags & Options

--my-ipUse the address you are connecting from
$ hubfly db network allow app-db --my-ip --label laptop
hubfly db exportdatabases
Docs

Export a database and download the file. Exports stay downloadable for 7 days.

$ hubfly db export app-db --format native --output app-db.dump
hubfly db resizedatabases
Docs

Change CPU, memory or storage after quoting the new monthly price. Storage can only grow.

$ hubfly db resize app-db --size medium --restart
hubfly storage createstorage
Docs

Create a Storage project in a region that offers Storage and print its S3 endpoint.

Flags & Options

--regionRegion id or name; picked interactively when omitted
$ hubfly storage create media
hubfly storage buckets createstorage
Docs

Create a bucket in a Storage project.

$ hubfly storage buckets create project-assets
hubfly storage lsstorage
Docs

List buckets, or the objects and sub-prefixes under a bucket prefix.

Flags & Options

--recursiveList every key under the prefix
$ hubfly storage ls project-assets/reports/
hubfly storage putstorage
Docs

Upload a file or a directory tree through a temporary upload URL, up to 20 GB per file.

Flags & Options

--recursiveUpload a directory under the key prefix
--content-typeOverride the detected content type
$ hubfly storage put ./dist project-assets/site/ --recursive
hubfly storage getstorage
Docs

Download an object to a file, or to standard output with -.

$ hubfly storage get project-assets/reports/hello.txt
hubfly storage keys createstorage
Docs

Create an S3 access key. The secret is printed once, or written into a Cell project with --to.

Flags & Options

--read-onlyRead permission instead of read-write
--bucketLimit the key to one bucket
--toWrite the S3 variables into a Cell project's environment
$ hubfly storage keys create web-app --bucket project-assets --to web
hubfly storage publishstorage
Docs

Register an object as a managed asset with public or protected delivery.

$ hubfly storage publish project-assets/images/logo.png
hubfly storage encodestorage
Docs

Encode a video object to HLS in the background; --wait follows the job.

$ hubfly storage encode project-assets/videos/intro.mp4 --max-height 720 --wait
hubfly realtime createrealtime
Docs

Create a Pusher-compatible WebSocket server after quoting its monthly price, then wait until it is ready.

Flags & Options

--size <preset>nano, small, medium, large or xlarge
--app <name>Name of the first app (default production)
--yesAccept the quoted price without a prompt
$ hubfly rt create chat --size nano --project new
hubfly realtime apps createrealtime
Docs

Add an app with its own keys and settings: origins, client events, encryption, history and limits.

$ hubfly rt apps create chat staging --origins https://staging.example.com
hubfly realtime keys rotaterealtime
Docs

Replace an app key; the old key keeps working for a grace period (24 hours by default).

$ hubfly rt keys rotate chat --app staging --grace 24h
hubfly realtime bindrealtime
Docs

Write the app's URL, id, key and secret (or the Laravel PUSHER_* set) into a Cell project.

Flags & Options

--presethubfly (HUBFLY_REALTIME_*) or laravel (PUSHER_*, VITE_PUSHER_*)
--client-prefixAlso write browser copies: NEXT_PUBLIC_, VITE_ or PUBLIC_
$ hubfly rt bind chat --to web --client-prefix VITE_
hubfly realtime publishrealtime
Docs

Trigger an event on one or more channels through the server API.

$ hubfly rt publish chat --channel orders --event order.updated --data '{"id":42}'
hubfly realtime tailrealtime
Docs

Stream the live inspector: connections, subscriptions, messages, API calls, errors and webhooks.

$ hubfly rt tail chat --family msg,conn
hubfly realtime webhooks createrealtime
Docs

Send signed webhook requests for channel, presence and connection events.

$ hubfly rt webhooks create chat --url https://api.example.com/hooks/realtime --events member_added
hubfly realtime keygenrealtime
Docs

Generate an end-to-end encryption master key locally for HUBFLY_REALTIME_E2E_KEYS. It is never sent to Hubfly space.

$ hubfly rt keygen --kid k2
hubfly analytics sites enableanalytics
Docs

Track a domain one of your Cell or Box projects serves on Hubfly space; HubProxy adds the script to its pages.

Flags & Options

--no-injectAdd the script yourself instead; prints the snippet
$ hubfly analytics sites enable --domain app.example.com
hubfly analytics sites createanalytics
Docs

Track a website hosted anywhere. Its domain must be verified first with hubfly analytics verify.

Flags & Options

--project newCreate a standalone Analytics project for the site
--retention <days>Keep raw events 30 to 365 days (30 by default)
$ hubfly analytics sites create example.com --project new --region <id|name>
hubfly analytics snippetanalytics
Docs

Print the script tag for every page's <head> and the URL of the server-side events API.

$ hubfly analytics snippet docs.example.com
hubfly analytics statsanalytics
Docs

Visitors, visits, pageviews, bounce rate and visit duration, with top pages and sources or one breakdown.

Flags & Options

--by <dimension>One breakdown, such as country or utm_campaign
--compareChange against the previous period
$ hubfly analytics stats docs --period 7d --compare
hubfly analytics realtimeanalytics
Docs

Visitors in the last 5 minutes, top pages, sources and countries, and the latest events.

Flags & Options

--watchRefresh every 10 seconds until Ctrl+C
$ hubfly analytics realtime docs --watch
hubfly analytics exportanalytics
Docs

Download raw events, visits or daily summaries, up to 8 MB per call.

$ hubfly analytics export docs --from 2026-10-01 --to 2026-10-07 --kind sessions -o sessions.csv
hubfly analytics keys createanalytics
Docs

Create an ingest key for the server-side events API. It is printed once.

$ hubfly analytics keys create docs backend
hubfly stream createstream
Docs

Create a live video server after quoting its speed price. Prints the first input's stream key once, with OBS settings.

Flags & Options

--speed <mbps>Outgoing bandwidth cap (default 25; the first 25 Mbps of every hour are free)
--input <name>Name of the first push input (default Main)
--yesAccept the quoted price without a prompt
$ hubfly stream create acme-tv --project new
hubfly stream inputs keys revealstream
Docs

Show an input's stream keys (and SRT passphrase) to configure an encoder. Keys are masked everywhere else; rotate them with keys rotate.

$ hubfly stream inputs keys reveal acme-tv Main
hubfly stream channels createstream
Docs

Create what viewers watch: a channel playing an input, mixer or playlist over WebRTC, LL-HLS and HLS.

Flags & Options

--backup <source>Source to play when the main source goes silent
--access tokenRequire signed playback tokens
--dvr <minutes>Rewind window, 0-360 minutes (needed for clips)
$ hubfly stream channels create acme-tv Main --source input:Main --dvr 60
hubfly stream destinations createstream
Docs

Restream to another platform. The platform's stream key is read from standard input, never from an argument.

Flags & Options

--stream-key-stdinRead the platform's stream key from standard input
--url <url>Ingest URL, required for custom and linkedin
--auto-startStart whenever the source goes live
$ hubfly stream destinations create acme-tv youtube --platform youtube --source channel:Main --stream-key-stdin
hubfly stream controlstream
Docs

Run live operations in one request: go live, restream, record, slate, disconnect, or any operation as JSON.

$ hubfly stream control acme-tv --go-live Main --destination-start youtube --record-start Main
hubfly stream pushstream
Docs

Publish a file or camera with your local ffmpeg. The CLI carries the stream itself, so the key never reaches ffmpeg's arguments.

Flags & Options

--loopRepeat a file until Ctrl-C
--key-stdinRead the stream key from standard input
--dry-runPrint the ffmpeg command without sending anything
$ hubfly stream push acme-tv show.mp4 --loop
hubfly stream tailstream
Docs

Follow the studio socket: events, live state changes and, with --meters, audio levels.

$ hubfly stream tail acme-tv --watch in:Main,ch:Main
hubfly stream playstream
Docs

Open a channel in mpv or ffplay, with a test token for token channels, or print the signed URL.

$ hubfly stream play acme-tv Main
hubfly serviceservice
Docs

Run CLI as background tunnel daemon with CORS-enabled REST API for desktop/IDE tools.

Flags & Options

--port <port>Custom HTTP port for daemon listener (default: 5600)
$ hubfly service --port 5600
hubfly updateservice
Docs

Check for new hubfly-cli GitHub releases and automatically update local binary.

Flags & Options

--checkOnly check for available updates without downloading binary
$ hubfly update --check

Exit Codes

hubfly prints errors on standard error and exits with a status that scripts can branch on:

CodeMeaning
0Success.
2Usage error: an unknown command, a missing argument or an invalid flag value, including confirmation required; re-run with --yes when no terminal is attached.
3Authentication or permission error: the token is missing, invalid or lacks access.
4Conflict: the resource is busy, already exists or is in the wrong state for the request.
5Any other failure, such as a rejected request or a failed operation.
6Timed out while waiting.
7The operation was cancelled or declined.

hubfly exec and hubfly ssh -- <cmd> exit with the remote command's status instead.

Config And Storage

Local CLI state lives under ~/.hubfly. CI can skip local files by setting HUBFLY_TOKEN.

  • ~/.hubfly/config.json: saved login token and profile data.
  • ~/.hubfly/tools: downloaded helper tools such as hubfly-builder.
  • ~/.hubfly/keys: generated key material for CLI connection flows.
  • ~/.hubfly/known_hosts: Hubfly space-managed SSH host keys.
  • ~/.hubfly/logs/debug.log: TUI debug output when HUBFLY_DEBUG=1 or --debug is used.

Token handling

Treat HUBFLY_TOKEN and personal access tokens as secrets. Do not commit them to source control or paste them into build logs.
Something unclear or out of date? Emailsupport@hubfly.spaceBack to top