hop3-cli 0.5.0.dev3

No project description provided

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 [e-mail]

# Or configure via environment
export HOP3_API_URL="ssh://[e-mail]"

# List applications (no app target needed)
hop3 apps

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

# From here on, app-scoped commands resolve myapp automatically:
hop3 logs
hop3 config set KEY=value
hop3 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 chains; 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.
6. hop3.toml [metadata].id — the project's canonical name. The "I'm physically standing in this project" source; outranks any server-level default so being inside a project always wins over a sticky binding from elsewhere.
7. Git remote hop3-<env> parsed for an app name — supports git push hop3-prod main style deploys.
8. Active server's default_app from ~/.config/hop3-cli/servers.toml — set via hop3 server use --default-app <app>. Lowest-priority fallback for single-app users.

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 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 splits the old "context" noun into two concepts:

• Server records — credentialed bindings to a Hop3 server. Live in ~/.config/hop3-cli/servers.toml. Managed with hop3 server (add / list / show / use / login / remove).
• Project contexts — environment-shaped overlays on a single project. Declared as [contexts.<name>] blocks inside hop3.toml. Managed with hop3 context from inside a project tree (init / use / list / show / add / remove). The currently-selected one is recorded in .hop3-local.toml (gitignored automatically).

A hop3 deploy from a project tree resolves: server (which Hop3 to talk to) + context (which environment of this project) + app (which app on that server) — 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.py         # Local commands (init, login, settings)
│   │   ├── 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

• User Guide
• CLI Reference
• Cheat Sheet
• CLI Migration Guide

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