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):
--app <name>/-a <name>— explicit flag, wins over everything.$HOP3_APP— environment variable for the current shell..hop3-app— one-line file in CWD or any ancestor up to$HOME. Drop it in a project repo andhop3from inside picks up the right app.hop3.toml [cli].app— same search path as.hop3-app, lower priority.hop3.toml [contexts.<resolved-context>].app— when a project context resolves (see below), itsappfield becomes the source. Lets one project map per-environment to different apps. Trusted only when the context was selected CWD-rooted (--contextor in-tree.hop3-local.toml); an ambiently-selected context still resolves but trips the project-mismatch guard.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 committedhop3.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-developerconfig.toml([contexts.<name>].server), so project-less commands (hop3 apps --context prod) can target a server by name.--contextresolves project-first, then global; there is no--serverflag. Managed withhop3 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 loginstores a bearer token in the per-server credential store (~/.config/hop3-cli/credentials.toml, mode0600), 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.tomlstays 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
Related Packages
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.