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 CLI
On Linux and macOS, install the latest release with the shell installer:
terminal
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.
| Platform | Install Path | Notes |
|---|---|---|
| Linux | curl ... | bash | Supports amd64 and arm64. |
| macOS | curl ... | bash | Supports Intel and Apple Silicon. |
| Windows | Manual release download | Download the hubfly_windows_*.zip asset from GitHub releases and add it to PATH. |
| Source build | go build -o hubfly . | Use this when developing the CLI locally. |
PATH check
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
2. Deploy from the current folder
terminal
3. Use a non-interactive deploy when scripting
terminal
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
| Goal | Command |
|---|---|
| Check the signed-in user | hubfly whoami |
| Open the project/container terminal UI | hubfly projects |
| Deploy the current app | hubfly deploy |
| Deploy with a Dockerfile | hubfly deploy --dockerfile ./deploy/Dockerfile --yes |
| Follow container logs | hubfly logs web-app --follow |
| Run one command in a container | hubfly exec web-app -- printenv |
| Open a shell | hubfly ssh web-app |
| Forward a private database | hubfly tunnel postgres-db 5432 5432 |
| Create a PostgreSQL database and connect an app | hubfly db create app-db --engine postgresql --project new, then hubfly db bind app-db --to web |
| Open a SQL client on a managed database | hubfly db connect app-db |
| Upload a file to Object Storage | hubfly storage put ./logo.png project-assets/images/ |
| Watch live Realtime traffic | hubfly rt tail chat |
| See who is on your website now | hubfly analytics realtime app.example.com --watch |
| See what a stream server has live | hubfly stream live acme-tv |
| Check for a CLI update | hubfly 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.
| Group | Use it to | Reference |
|---|---|---|
hubfly login, logout, whoami | Sign in with a personal access token and check the account. | Authentication |
hubfly deploy, hubfly build | Build the current folder and deploy it to a Cell project. | Deploy, Build config |
hubfly stack | Deploy a Docker Compose file as a group of services. | Stack |
hubfly tunnel, ssh, exec, logs | Reach private ports, open shells, run commands and follow logs. | Tunnels & exec |
hubfly db | Create, connect to, query and operate managed PostgreSQL, MySQL and SQLite (libSQL). | Managed Databases |
hubfly storage | Manage 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 analytics | Add 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 projects | Browse projects, containers, metrics and tunnels in a terminal UI. | Terminal UI |
hubfly service, update | Run 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 --detachCommand Search
Filter every CLI command, flag, and example from one place.
hubfly loginauthAuthenticate 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_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdefhubfly logoutauthInvalidate local CLI auth session and clear stored tokens from ~/.hubfly/config.json.
$ hubfly logouthubfly whoamiauthDisplay currently authenticated account user name, email, and organization binding.
$ hubfly whoamihubfly projectstuiLaunch 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_123hubfly deploydeployBuild 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 --detachhubfly build initconfigInitialize 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/Dockerfilehubfly build validateconfigVerify 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 --jsonhubfly build explainconfigInspect what hubfly-builder auto-detects and explain generated Dockerfile/run steps.
Flags & Options
--jsonOutput detection report as JSON$ hubfly build explain --jsonhubfly stack planstackInspect 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.ymlhubfly stack upstackDeploy 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 --yeshubfly stack statusstackShow live runtime status for all services declared in local stack state.
$ hubfly stack statushubfly stack logsstackStream combined stdout and stderr logs for all or selected stack services.
Flags & Options
-f, --followContinuously tail live stack logs$ hubfly stack logs api db -fhubfly stack downstackTear down stack services in reverse dependency order.
Flags & Options
--volumesDelete associated stack persistent storage volumes$ hubfly stack down --volumes --yeshubfly tunneltunnelsEstablish encrypted Yamux WebSocket tunnel from localhost port to private container port.
$ hubfly tunnel postgres-db 5432 5432hubfly sshtunnelsOpen interactive PTY shell session or run non-interactive command inside container.
$ hubfly ssh api-server -- ls -la /app/datahubfly exectunnelsExecute single command with 55s timeout inside target container.
$ hubfly exec web-app -- printenvhubfly logstunnelsStream real-time container log output directly to local terminal.
Flags & Options
-f, --followKeep log connection open and stream new lines$ hubfly logs web-app -fhubfly db createdatabasesCreate 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 newhubfly db connectdatabasesStart 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 urldatabasesPrint 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 --revealhubfly db querydatabasesRun 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 binddatabasesWrite 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 webhubfly db network allowdatabasesAdd 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 laptophubfly db exportdatabasesExport a database and download the file. Exports stay downloadable for 7 days.
$ hubfly db export app-db --format native --output app-db.dumphubfly db resizedatabasesChange CPU, memory or storage after quoting the new monthly price. Storage can only grow.
$ hubfly db resize app-db --size medium --restarthubfly storage createstorageCreate 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 mediahubfly storage buckets createstorageCreate a bucket in a Storage project.
$ hubfly storage buckets create project-assetshubfly storage lsstorageList 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 putstorageUpload 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/ --recursivehubfly storage getstorageDownload an object to a file, or to standard output with -.
$ hubfly storage get project-assets/reports/hello.txthubfly storage keys createstorageCreate 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 webhubfly storage publishstorageRegister an object as a managed asset with public or protected delivery.
$ hubfly storage publish project-assets/images/logo.pnghubfly storage encodestorageEncode a video object to HLS in the background; --wait follows the job.
$ hubfly storage encode project-assets/videos/intro.mp4 --max-height 720 --waithubfly realtime createrealtimeCreate 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 newhubfly realtime apps createrealtimeAdd 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.comhubfly realtime keys rotaterealtimeReplace an app key; the old key keeps working for a grace period (24 hours by default).
$ hubfly rt keys rotate chat --app staging --grace 24hhubfly realtime bindrealtimeWrite 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 publishrealtimeTrigger 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 tailrealtimeStream the live inspector: connections, subscriptions, messages, API calls, errors and webhooks.
$ hubfly rt tail chat --family msg,connhubfly realtime webhooks createrealtimeSend signed webhook requests for channel, presence and connection events.
$ hubfly rt webhooks create chat --url https://api.example.com/hooks/realtime --events member_addedhubfly realtime keygenrealtimeGenerate an end-to-end encryption master key locally for HUBFLY_REALTIME_E2E_KEYS. It is never sent to Hubfly space.
$ hubfly rt keygen --kid k2hubfly analytics sites enableanalyticsTrack 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.comhubfly analytics sites createanalyticsTrack 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 snippetanalyticsPrint the script tag for every page's <head> and the URL of the server-side events API.
$ hubfly analytics snippet docs.example.comhubfly analytics statsanalyticsVisitors, 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 --comparehubfly analytics realtimeanalyticsVisitors 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 --watchhubfly analytics exportanalyticsDownload 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.csvhubfly analytics keys createanalyticsCreate an ingest key for the server-side events API. It is printed once.
$ hubfly analytics keys create docs backendhubfly stream createstreamCreate 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 newhubfly stream inputs keys revealstreamShow 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 Mainhubfly stream channels createstreamCreate 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 60hubfly stream destinations createstreamRestream 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-stdinhubfly stream controlstreamRun 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 Mainhubfly stream pushstreamPublish 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 --loophubfly stream tailstreamFollow the studio socket: events, live state changes and, with --meters, audio levels.
$ hubfly stream tail acme-tv --watch in:Main,ch:Mainhubfly stream playstreamOpen a channel in mpv or ffplay, with a test token for token channels, or print the signed URL.
$ hubfly stream play acme-tv Mainhubfly serviceserviceRun 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 5600hubfly updateserviceCheck for new hubfly-cli GitHub releases and automatically update local binary.
Flags & Options
--checkOnly check for available updates without downloading binary$ hubfly update --checkExit Codes
hubfly prints errors on standard error and exits with a status that scripts can branch on:
| Code | Meaning |
|---|---|
0 | Success. |
2 | Usage error: an unknown command, a missing argument or an invalid flag value, including confirmation required; re-run with --yes when no terminal is attached. |
3 | Authentication or permission error: the token is missing, invalid or lacks access. |
4 | Conflict: the resource is busy, already exists or is in the wrong state for the request. |
5 | Any other failure, such as a rejected request or a failed operation. |
6 | Timed out while waiting. |
7 | The 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 ashubfly-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 whenHUBFLY_DEBUG=1or--debugis used.
Token handling
HUBFLY_TOKEN and personal access tokens as secrets. Do not commit them to source control or paste them into build logs.