Metadata-Version: 2.4
Name: hivepods-cli
Version: 0.4.3
Summary: Command line interface for DockHive / HivePods
Author: DockHive
License: MIT
Project-URL: Homepage, https://github.com/DockHive/hive-cli
Project-URL: Issues, https://github.com/DockHive/hive-cli/issues
Keywords: dockhive,hivepods,cli,pods,environments,cloud,deploy,mcp
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: websockets>=12.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"

# HivePods

Host your apps, run managed databases and your own cloud dev environments on DockHive,
right from your terminal.

```bash
cd my-app && hivepod deploy   # Drone reads your code, builds your app and deploys it
hivepod app list              # your apps, their URLs and where they deploy from
hivepod create web1           # a dev environment: name it, pick an OS + size
hivepod connect web1          # you're in a shell
```

Only here for app hosting? `hivepod deploy` and `hivepod app …` are all you need
(see [App hosting](#app-hosting)).

## Install

macOS / Linux:

```bash
curl -fsSL https://dockhive.io/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://dockhive.io/install.ps1 | iex
```

The installer puts `hivepod` in its own folder (`~/.hivepods`), adds it to your PATH and
works in every new terminal. Run it again any time to upgrade.

Prefer pip? `pipx install hivepods-cli` does the same. With plain `pip install hivepods-cli`
the `hivepod` command may land in a folder that isn't on your PATH; `python3 -m hivepods_cli`
always works.

Once a day `hivepod` checks whether a newer version is out and, if so, says so (on
stderr, after the command) with the upgrade command for how you installed it: rerun the
installer, or `pipx upgrade hivepods-cli`. It never runs on CI (`CI` set), in
`hivepod mcp`, or when `HIVEPODS_NO_UPDATE_CHECK=1` is set.

## Get started

```bash
hivepod login           # opens your browser to sign in
hivepod create          # short wizard: name, OS, size
hivepod connect myenv   # open a shell in your environment
hivepod list            # see everything you're running
```

`hivepod login` signs you in through the browser. On a machine with no browser,
use `hivepod login --no-browser` for email and password instead.

No servers to manage, no setup. Each environment gets its own address
(`myenv.dockhive.sh`), so whatever you run inside is reachable.

## Everyday commands

```bash
hivepod create                       # interactive: OS, size (or custom CPU/RAM/disk), region
hivepod create api --os ubuntu-24.04 --size small    # or one-liner

hivepod connect api                  # interactive shell
hivepod exec api "npm test"          # run a single command (up to ~20 seconds)
hivepod exec --detach api "npm ci && npm run build"   # a background job: prints its id
hivepod job status api <job-id> --follow             # stream it; exits with its exit code
hivepod jobs api                     # recent jobs; `hivepod job cancel api <job-id>` stops one
hivepod logs api -f                  # follow live logs
hivepod cp ./site api:/home/hivepod/projects/site   # copy files in (folders too)
hivepod cp api:/home/hivepod/data/dump.sql .        # ... and out

hivepod stop api                     # pause (your data stays)
hivepod start api                    # resume
hivepod restart api
hivepod rm api                       # delete (its backups are kept for 7 days)

hivepod list                         # what you have
hivepod status api                   # details, disk used vs size, live CPU/RAM

hivepod env api LOG_LEVEL=info --unset DEBUG   # change environment variables
hivepod apply api                    # use them (re-creates the pod: data/ and projects/ are kept, the rest is reset)

hivepod backup create api            # back up the data/ and projects/ folders
hivepod backup list
hivepod backup restore <backup-id> api-copy   # a NEW environment from a backup
hivepod backup list --deleted        # backups of deleted pods, and when they are purged
```

Deleting a pod keeps its backups for 7 days: `hivepod rm` says how many and until
when. During that time `hivepod backup list --deleted` shows them and
`hivepod backup restore <backup-id> <new-name>` restores one into a new pod;
`hivepod backup rm <backup-id>` deletes one straight away. After 7 days they are
purged automatically.

Anywhere a command takes a name, you can pass the environment's id instead.
`start`, `stop`, `restart`, `suspend`, `resume`, `apply`, `rm`, `backup create`
and `backup restore` wait until the work is done; add `--no-wait` to return
straight away.

`hivepod cp` copies between this computer and `/home/hivepod/projects` or
`/home/hivepod/data` in a running pod (relative pod paths are under `projects`).
Like `docker cp`: a folder copied to an existing folder lands inside it, to a new
path it becomes that path, and `./site/.` copies just the contents. Nothing is
excluded (it's an explicit copy, `.env` files included); uploads are sent in chunks
with a progress bar, up to 200 MiB packed per copy.

`hivepod connect` works on macOS, Linux and Windows (Windows Terminal or the
Windows 10+ console).

### Long-running commands and CI

`hivepod exec` is for quick commands: it stops after about 20 seconds. For builds,
installs, migrations and test suites, start a background job:

```bash
JOB=$(hivepod exec --detach --timeout 1800 api "cd /home/hivepod/projects/app && git pull && make deploy")
hivepod job status api "$JOB" --follow    # streams the output, exits with the job's exit code
```

Jobs run in the pod (as the same user as `exec`, from `/home/hivepod/projects`) and
keep going if your terminal or CI runner disconnects. The default timeout is 1 hour
(max 6 hours); up to 3 run at once per pod. `--wait` waits without printing the
output; exit codes are the job's own, 124 when it timed out and 130 when cancelled.

Inside a pod, `TMPDIR` and the npm/pip caches live on `/home/hivepod/data`, and
`hivepod-info` shows the pod's real CPU, memory and disk limits (`free` and `df`
show the whole machine's). Applying settings re-creates the pod: only
`/home/hivepod/data` and `/home/hivepod/projects` are kept (root's `~/.ssh` lives in
`/home/hivepod/data/.ssh`, so it is kept too).

Safe requests (reads, and `start`/`stop`/`restart`/`suspend`/`resume`) are retried
a couple of times when DockHive answers with a temporary error. Error messages
include the HTTP status and a request id to quote to support.

## Ports and custom domains

One pod can run several apps, each on its own HTTPS address:

```bash
hivepod expose api 5100                  # -> https://api-5100.dockhive.sh
hivepod expose api 3000 --subdomain shop # -> https://shop.dockhive.sh
hivepod ports api                        # main address + every exposed port
hivepod unexpose api 3000                # remove it (asks first; -y to skip)

hivepod domain add api www.example.com             # on the main address
hivepod domain add api api.example.com --port 5100 # on an exposed port
hivepod domain verify api api.example.com          # check DNS, turn on HTTPS
hivepod domain list api [--port 5100]
hivepod domain rm api api.example.com
```

The app must listen on `0.0.0.0:<port>` inside the pod. Addresses carry HTTP, HTTPS and
WebSocket traffic. `domain add` prints the DNS records to create (a CNAME to the port's
target and a TXT record); removing a port also removes the custom domains on it.

## Databases

Managed databases are closed to the internet by default: only the sources you allow
can connect.

```bash
hivepod db list                                   # firewall column flags OPEN TO INTERNET
hivepod db info shop                              # details + firewall state (no password)
hivepod db firewall shop                          # rules, and what each resolves to now
hivepod db firewall shop allow 203.0.113.4        # your IPv4 address (or a CIDR, e.g. a CI range)
hivepod db firewall shop allow --app shop-api     # an app in the database's region
hivepod db firewall shop allow --pod web          # a pod in the database's region
hivepod db firewall shop allow --all-pods         # all your pods in that region (or --all-apps)
hivepod db firewall shop remove 7                 # remove rule 7
hivepod db firewall shop deny-all                 # close it: only the allow rules can connect
```

`--app` / `--pod` rules follow the workload's internal address when it is redeployed;
they only work for workloads in the same region as the database. IPv4 only.
`hivepod db firewall <db> open --yes` opens a database to the whole internet (not
recommended).

### Upgrading PostgreSQL

Move a PostgreSQL database to a newer major version in place. `hivepod db info` shows
`Upgrade available: 16, 17` when there is one.

```bash
hivepod db upgrade shop --to 17             # explains what happens, asks, then follows progress
hivepod db upgrade shop --to 17 --yes       # no prompt (scripts, CI)
hivepod db upgrade shop --to 17 --no-wait   # start it and return
hivepod db upgrade shop --status            # where the current (or last) upgrade is
hivepod db upgrade shop --rollback          # back to the previous version (within 7 days)
```

- **Nothing to reconfigure.** Host, port, database name, username, password, TLS and
  firewall rules stay the same.
- **A backup is taken first.** The data is then copied to the new version; the database
  is unavailable for a short time during the final copy (bigger databases take longer).
- **Automatic rollback.** If any step fails, the database goes back to the version it
  was on and the command exits non-zero with the reason.
- **Manual rollback for 7 days.** The previous version is kept for 7 days.
  `--rollback` puts it back, but **every change made since the upgrade is lost**.

Progress is shown step by step: Queued, Backing up, Copying to PostgreSQL 17,
Checking, Switching, Done. Only newer major versions of PostgreSQL can be upgraded to.

### Moving Redis 7 to Valkey 8

New Redis databases run Valkey 8, the open-source fork of Redis (fully compatible with
Redis clients, commands and connection URLs). A Redis 7 database can move to it in
place; `hivepod db info` shows `Move to Valkey 8 available`.

```bash
hivepod db upgrade cache --to valkey-8      # also accepts "valkey" / "Valkey 8"
hivepod db upgrade cache --status
hivepod db upgrade cache --rollback         # back to Redis 7 (within 7 days)
```

Same connection details, a backup first, automatic rollback, and the Redis 7 data kept
for 7 days, as above. While the data is copied, **writes are paused** (they wait, then
go through on Valkey) and reads keep working. Progress: Backing up, Copying to Valkey
8, Checking, Switching, Done. Rolling back loses every change made since the move.

## Deploy an app

```bash
cd my-app
hivepod deploy                      # upload this folder; Drone builds and deploys it
hivepod deploy ./api --env DATABASE_URL=postgres://...   # set env vars (repeatable)
hivepod deploy --app my-api         # redeploy a specific app
hivepod deploy --no-wait            # return once the upload is accepted
hivepod deploy --region eu          # put a new app in a region (e.g. next to its pod)
```

A new app goes to the region you set with `hivepod config set region <name>`, or
DockHive's default region. An app you deployed before stays in its region.

Zero config: **Drone**, DockHive's AI deploy agent, reads your code, builds your app and
deploys it, and fixes problems along the way so it goes live. You see Drone's progress as
it works ("Reading your code…", "Building your app…"), then the live URL. If your app
needs settings such as `DATABASE_URL`, Drone tells you which ones; pass them with `--env`.
`--verbose` shows the full build log. Deploying the same folder again updates the
same app (`--new` makes a separate one). If the folder isn't a web service (a mobile or
desktop app, a CLI or library, a background worker, notebooks, infrastructure config),
Drone stops before building, says what it found and what to do instead (deploy the
backend folder, or use a HivePod), and nothing is billed.

What gets uploaded: the folder as a compressed archive (50 MB max) without `.git`,
`node_modules`, virtualenvs, `__pycache__`, tool caches, large `dist`/`build` folders,
and never your secrets (`.env*` except `.env.example`/`.env.sample`, `*.pem`, `*.key`,
`id_rsa*`). Files matched by your `.gitignore` are skipped too; add a `.dockhiveignore`
(same format) for anything else you don't want to ship. Ignore files support the common
gitignore syntax: `*`, `**`, `?`, `[abc]`, `!negation`, a trailing `/` for folders and a
leading `/` to anchor at the project root; only the files in the project root are read.

## App hosting

Deploy a folder or a GitHub repository, then manage the app from the terminal. Anywhere a
command takes `<app>`, use the app's id, its name or its address (`shop` for
`shop.dockhive.app`).

```bash
hivepod deploy                              # upload this folder
hivepod deploy --repo                       # deploy this folder's GitHub repo (its origin remote)
hivepod deploy --repo --auto-deploy         # ... and redeploy on every push
hivepod deploy --repo https://github.com/me/shop --branch main

hivepod app list                            # name, status, region, URL, source, auto-deploy
hivepod app status shop                     # details, health, last deployment, domains
hivepod app deployments shop                # versions with commit, author and time
hivepod app logs shop -f                    # what the live app prints (--since 10m, --lines 500)
hivepod app logs shop --build latest        # a deployment's build log (id, version or latest)
hivepod app rollback shop 4                 # put version 4 back live
hivepod app redeploy shop                   # rebuild a GitHub app from its branch
hivepod app env shop                        # variable names (values are never shown)
hivepod app env shop API_KEY=... --unset OLD   # set / remove; applies on the next deploy
hivepod app auto-deploy shop on --branch main  # or off; no argument shows the state
hivepod app rm shop                         # delete (type the app's id to confirm)

hivepod app domain add shop www.shop.com    # prints the DNS records to create
hivepod app domain verify shop www.shop.com # shows each DNS check; turns on HTTPS when right
hivepod app domain list shop
hivepod app domain redirect shop shop.com --to www.shop.com   # --off to stop
hivepod app domain rm shop www.shop.com
```

`hivepod apps` works as well as `hivepod app`.

**Uploads and GitHub.** `hivepod deploy` uploads the folder. With `--repo`, DockHive
fetches the code from the repository instead (your connected GitHub account is used for
private repositories); without a URL it uses the folder's `origin` remote. An app you
deployed by upload switches to the repository when you deploy its folder with `--repo`:
it keeps its URL, custom domains and history. Auto-deploy (redeploy on every push) needs
a GitHub app; `hivepod deploy` in a GitHub clone reminds you of `--repo --auto-deploy`.

**Custom domains.** `domain add` prints the records to create at your DNS provider (a
CNAME for routing and a TXT record proving the domain is yours) and notes for root domains
(use ALIAS/ANAME/flattening) and Cloudflare (set the records to DNS only). Run
`domain verify` once they are in place; it shows which checks passed. A domain that is
never verified is released after 3 days; `domain add` and `domain list` show the date.

## AI agents (MCP)

`hivepod mcp` is an [MCP](https://modelcontextprotocol.io) server, so Claude, Cursor,
Windsurf and other AI coding tools can deploy and manage your DockHive resources for you.
It uses your `hivepod login` session; sign in once in a terminal first.

```bash
hivepod login
hivepod mcp --print-config     # prints the snippets below with your hivepod path filled in
```

**Claude Code**

```bash
claude mcp add dockhive -- hivepod mcp
# every project: claude mcp add --scope user dockhive -- hivepod mcp
```

**Claude Desktop, Cursor, Windsurf**: add this to `claude_desktop_config.json`
(Settings → Developer → Edit Config), `~/.cursor/mcp.json`, or
`~/.codeium/windsurf/mcp_config.json`. Desktop apps don't see your shell's PATH, so use
the full path to `hivepod` (`~/.hivepods/bin/hivepod` with the installer; on Windows
`%USERPROFILE%\.hivepods\cli\Scripts\hivepod.exe`; `hivepod mcp --print-config` shows
yours):

```json
{
  "mcpServers": {
    "dockhive": {
      "command": "/Users/you/.hivepods/bin/hivepod",
      "args": ["mcp"]
    }
  }
}
```

Then ask, for example: *"Deploy this project to DockHive"*, *"Why did the last deploy
fail?"*, *"Add a Postgres database and wire it into the app"*.

| Tool | What it does |
|------|--------------|
| `deploy` | Deploy a folder (`path`) or a GitHub repo (`repo_url`) with Drone; waits and returns the URL, or Drone's summary of the app, the env vars it needs and the build log tail on failure. Code that isn't a web service (mobile/desktop app, CLI, library, worker, notebooks, infra config) is an error with `kind`, `reason`, `suggestion` and `retryable: false` |
| `deployment_status`, `build_logs` | Follow a deployment and read its build log |
| `list_apps`, `app_logs` | Your apps, and a live app's runtime logs |
| `set_env` | Set/unset an app's environment variables (values are write-only), optionally redeploy |
| `redeploy`, `rollback` | Rebuild a repository-based app; put an earlier version back live |
| `add_domain`, `domain_status`, `remove_domain`, `app_domains_list` | Custom domains: the DNS records to create, verification, removal, an app's domains |
| `app_auto_deploy` | Show or turn on/off redeploying a GitHub app on every push |
| `list_pods`, `create_pod`, `exec_in_pod` | HivePods: list, create, run a command |
| `start_pod_job`, `pod_job_status`, `cancel_pod_job` | HivePods: long-running background jobs |
| `list_ports`, `expose_port`, `unexpose_port` | A pod's HTTPS addresses: list, expose a port, remove one (`confirm: true`) |
| `pod_upload`, `pod_download` | Copy files into / out of a pod (`hivepod cp`) |
| `list_databases`, `create_database`, `database_connection` | Managed databases, their connection strings and firewall state (`open_to_internet`) |
| `database_firewall`, `database_firewall_allow`, `database_firewall_remove`, `database_firewall_default` | Database firewall: list rules; allow an IPv4 address/CIDR, an app or pod (same region); remove a rule; default deny (opening to the internet needs `confirm: true`) |
| `database_upgrade` | PostgreSQL major-version upgrades or Redis 7 → Valkey 8 (`version: "valkey-8"`): status (no `version`), start one (`version`), or `action: "rollback"`; starting or rolling back needs `confirm: true` |
| `usage_and_cost` | Plan, usage this period and an estimated bill |
| `delete_app`, `delete_pod` | Permanent deletes; refuse unless called with `confirm: true` |

Safety notes:

- **Secrets stay local.** `.env` files, private keys and certificates are never uploaded,
  even if an ignore file says otherwise. Configuration goes in through `env` / `set_env`,
  where values are stored encrypted and never shown back.
- **Deletes need confirmation.** `delete_app` and `delete_pod` only describe what would be
  deleted until they are called with `confirm: true`; agents are told to ask you first.
  Deleting a pod keeps its backups for 7 days (restorable into a new pod), and
  `delete_pod` says how many and until when.
- **Upgrades need confirmation too.** `database_upgrade` explains what an upgrade or a
  rollback does and only starts it when called with `confirm: true`.
- **Your session, your permissions.** The server acts as the account you signed in with
  `hivepod login`. `hivepod logout` cuts it off.
- The server speaks MCP over stdio and writes only protocol messages to stdout; set
  `HIVEPODS_MCP_LOG=INFO` to see its log on stderr.

## Operating systems

Ubuntu, Debian, Fedora, Alpine, Arch, Rocky and more run as fast, lightweight
environments. **Windows** and **FreeBSD** run as full machines — reach those
through the built-in web console (or RDP for Windows) instead of a shell.

```bash
hivepod os              # everything you can launch
```

## Sizes

Pick a preset, or set your own:

| Size | vCPU | RAM | Disk |
|------|------|-----|------|
| nano | 0.5 | 512 MB | 5 GB |
| micro | 1 | 1 GB | 10 GB |
| small | 2 | 2 GB | 25 GB |
| medium | 4 | 4 GB | 50 GB |
| custom | your call | your call | your call |

## Settings

```bash
hivepod config set default_size small   # your default when you don't pick one
hivepod config set region eu            # your default region for new pods and apps
hivepod config list
```

## Help

```bash
hivepod --help
hivepod <command> --help
```
