Skip to main content

hop3-cli

Command-line interface for interacting with Hop3 servers.

Overview

hop3-cli is a thin client that communicates with hop3-server via JSON-RPC over HTTP or SSH tunneling. It provides a familiar Heroku-like CLI experience for deploying and managing applications.

Features

  • Application management: Deploy, start, stop, restart, and scale applications
  • Environment variables: Securely manage app configuration
  • Log streaming: View real-time application logs
  • Addon management: Provision and manage backing services (PostgreSQL, Redis, MySQL)
  • SSH tunneling: Secure communication with remote servers
  • Multiple output formats: Human-readable, JSON, or quiet mode

Installation

pip install hop3-cli

Quick Start

# Initialize connection to a Hop3 server
hop3 init user@hop3.example.com

# Or configure via environment
export HOP3_API_URL="ssh://user@hop3.example.com"

# List applications (no app target needed)
hop3 apps

# Bind a default app for this shell/context (sticky)
hop3 use --app myapp

# From here on, app-scoped commands resolve myapp automatically:
hop3 app logs
hop3 config set KEY=value
hop3 app restart

App Resolution

Commands that act on a single app (logs, restart, config set, run, …) no longer take the app name as a positional argument. Instead the CLI resolves it from a layered chain, walking sources until one supplies a value (ADR 042 §Resolution; supersedes ADR 036 §D7):

  1. --app <name> / -a <name> — explicit flag, wins over everything.
  2. $HOP3_APP — environment variable for the current shell.
  3. .hop3-app — one-line file in CWD or any ancestor up to $HOME. Drop it in a project repo and hop3 from inside picks up the right app.
  4. hop3.toml [cli].app — same search path as .hop3-app, lower priority.
  5. hop3.toml [contexts.<resolved-context>].app — when a project context resolves (see below), its app field becomes the source. Lets one project map per-environment to different apps. Trusted only when the context was selected CWD-rooted (--context or in-tree .hop3-local.toml); an ambiently-selected context still resolves but trips the project-mismatch guard.
  6. hop3.toml [metadata].id — the project's canonical name. The "I'm physically standing in this project" source, so being inside a project always wins over a sticky binding from elsewhere.

Use hop3 --why <command> to print the full trace and see which source won. --why is diagnostic-only: the command itself is not executed (so hop3 deploy --why is safe to run).

# Explicit (always works):
hop3 app logs --app myapp
hop3 config set --app myapp KEY=value

# Per-shell:
export HOP3_APP=myapp

# Per-directory (legacy pin file):
echo myapp > .hop3-app

# Per-project, declared in hop3.toml:
# [metadata]
# id = "myapp"
# [contexts.staging]
# app = "myapp-staging"

# Debug:
hop3 --why logs

The ADR 042 model has a single managed noun — the context — and a single selector, --context <name>, for every command (app-bound or not).

  • Contexts — a named target at two scopes. A project context (dev / staging / prod) is declared as a [contexts.<name>] block inside the committed hop3.toml: a non-secret bundle of server address + app + domains + env. A global context is a name bound to a server address in the per-developer config.toml ([contexts.<name>].server), so project-less commands (hop3 apps --context prod) can target a server by name. --context resolves project-first, then global; there is no --server flag. Managed with hop3 context (add / use / list / show / remove / rename) — project scope inside a project tree, global scope outside one (or with --global). The per-checkout project selection is recorded in .hop3-local.toml (gitignored automatically).
  • Credentials are invisible plumbing — there is no "server" noun to manage. hop3 login stores a bearer token in the per-server credential store (~/.config/hop3-cli/credentials.toml, mode 0600), keyed by the server's canonical address, and records that server as the default target; hop3 login --context <name> also names it as a global context and the default. config.toml stays secret-free (local preferences, global contexts, [cli].default_context).

A hop3 deploy from a project tree resolves the context (which environment of this project, and therefore which server and app), and shows a preview-and-confirm prompt with the plan before invoking the deploy RPC. --dry-run exits after printing the plan; --force bypasses the project-mismatch safety guard.

See CLI Reference: App Resolution and ADR 042 for the full specification.

Configuration

Configuration can be set via environment variables or config file (~/.config/hop3-cli/config.toml).

Variable Description Default
HOP3_API_URL Server URL (HTTP or SSH) -
HOP3_API_TOKEN Authentication token -
HOP3_APP Default app for app-scoped commands -
HOP3_CONTEXT Active context name -
HOP3_DEV_MODE Enable development mode false

Architecture

hop3-cli/
├── src/hop3_cli/
│   ├── main.py              # Entry point, argument parsing
│   ├── config.py            # Configuration management
│   ├── core/
│   │   └── resolution.py    # App resolution chain (ADR 036 D7)
│   ├── rpc/
│   │   └── client.py        # JSON-RPC client with SSH tunnel
│   ├── commands/
│   │   ├── local/           # Local commands (init, login, settings, context)
│   │   ├── flags.py         # CLI flag parsing (--app, --why, --json, -y, …)
│   │   └── destructive.py   # Confirmation prompts
│   └── ui/
│       └── rich_printer.py  # Output formatting
└── tests/

Development

# Run tests
uv run pytest tests/ -v

# Lint and format
uv run ruff check src/
uv run ruff format src/

Documentation

  • hop3-server - The server that hop3-cli communicates with
  • hop3-tui - Alternative terminal UI interface

License

Apache-2.0 - Copyright (c) 2024-2026, Abilian SAS

Metadata

Release files for hop3-cli 0.8.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hop3-cli 0.8.2
File Size Uploaded Provenance Actions
hop3_cli-0.8.2.tar.gz 165.5 kB Without provenance Details for hop3_cli-0.8.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hop3-cli 0.8.2
File Interpreter ABI Platform Actions
hop3_cli-0.8.2-py3-none-any.whl Python 3 none any Details for hop3_cli-0.8.2-py3-none-any.whl

Total release size: 369.5 kB

Release files / hop3_cli-0.8.2.tar.gz

Download URL hop3_cli-0.8.2.tar.gz
Size 165.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c28eaddc8ff0795a716a03766ea4affe4e5ce01d235593aaf122a8d015b557a3
BLAKE2b-256 checksum
How to use checksums
2350f2ad462d2f010cf9f5fa0d5a907ae1e11d416de8c54f461eac3f7962ea86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / hop3_cli-0.8.2-py3-none-any.whl

Download URL hop3_cli-0.8.2-py3-none-any.whl
Size 203.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
be417d45393bbe3877f8780464ddfa686bf8052e64bba75e25c5f56d50620c04
BLAKE2b-256 checksum
How to use checksums
e9b504dd5a020900e272db50e423c66c7e5312d71c55a8cd2297c716460b3cb4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for hop3-cli 0.8.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page