Metadata-Version: 2.4
Name: hivepods-cli
Version: 0.2.1
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

Your own cloud dev environment, ready in seconds. Pick an operating system,
choose how much power you need, and you're in — right from your terminal.

```bash
hivepod create web1     # a quick wizard: name it, pick an OS + size
hivepod connect web1    # you're in a shell
```

## 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.

## 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
hivepod logs api -f                  # follow live logs

hivepod stop api                     # pause (your data stays)
hivepod start api                    # resume
hivepod restart api
hivepod rm api                       # delete

hivepod list                         # what you have
hivepod status api                   # details + live CPU/RAM

hivepod env api LOG_LEVEL=info --unset DEBUG   # change environment variables
hivepod apply api                    # use them (recreates the environment; data/ and projects/ are kept)

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
```

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 connect` works on macOS, Linux and Windows (Windows Terminal or the
Windows 10+ console).

## 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
```

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.

## 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` | Custom domains: the DNS records to create, verification, removal |
| `list_pods`, `create_pod`, `exec_in_pod` | HivePods: list, create, run a command |
| `list_databases`, `create_database`, `database_connection` | Managed databases and their connection strings |
| `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.
- **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 list
```

## Help

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