Metadata-Version: 2.5
Name: highhxcli
Version: 0.4.0
Summary: HighhX — the developer command center CLI, with HighhX Pro: an AI developer agent in your terminal.
Author: HighhX contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,automation,cli,coding-agent,developer-tools,devops,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Provides-Extra: ai
Requires-Dist: anthropic>=1.0; extra == 'ai'
Requires-Dist: google-genai>=1.20; extra == 'ai'
Requires-Dist: openai>=1.40; extra == 'ai'
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anthropic>=1.0; extra == 'dev'
Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
Requires-Dist: google-genai>=1.20; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: openai>=1.40; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.20; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Description-Content-Type: text/markdown

# HighhX

**HighhX is a developer command center for your terminal.** One CLI — `highhx` — detects
your project, runs your workflows, manages environments, dependencies, tests,
builds, git, releases, deployments, services and databases, and keeps a searchable
history of everything it did. Every risky action is classified and needs approval.

| | |
|---|---|
| **HighhX Free** | The interactive `highhx` session and the full developer CLI: known requests in plain language run locally without AI, plus every command, shell commands with risk checks and approvals, and browser/desktop automation with known targets (`highhx computer`, `highhx do`). Local, no account, no AI. |
| **HighhX Pro** | The same session with the AI developer agent attached — it plans, changes code, runs your tools, operates browsers and apps (AI computer use), recovers from failures and verifies the result. |

Run `highhx` in a terminal and describe what you want. Free and Pro share one interface and
one execution platform: the same tools, safety policy, confirmations, verification and audit
trail. Your plan only decides which capabilities the session has — the HighhX platform grants
and enforces them. The AI only chooses actions; it never gets its own way to run them.

```text
$ highhx doctor

HighhX Doctor

✓ macOS 15.2 arm64
✓ HighhX on Python 3.13.1
✓ git 2.47.1
✓ node 22.12.0
✓ python satisfies >=3.11 — declared in pyproject.toml
✓ Configuration valid
✓ Workflows valid — 7 workflow(s)
⚠ docker unavailable — required by this project
✗ Missing DATABASE_URL — profile development

Suggested actions
  → Install docker and make sure it is on PATH.
  → Set it with `highhx env set DATABASE_URL --profile development` or export it in your shell.
```

- [Why HighhX](#why-highhx)
- [Installation](#installation)
- [Quick start](#quick-start)
- [The interactive session](#the-interactive-session)
- [HighhX Pro: the AI developer agent](#highhx-pro-the-ai-developer-agent)
- [Commands](#commands)
- [Workflows](#workflows)
- [Configuration](#configuration)
- [Plugins](#plugins)
- [Security model](#security-model)
- [Development](#development)
- [Contributing](#contributing)

## Why HighhX

Most projects accumulate a pile of scripts, Makefile targets, README snippets and
CI YAML that only half the team remembers. HighhX gives every project the same
front door:

- **Local-first CLI.** Every Free command works without an account or network.
  History, logs and deployment state live in `.highhx/` on your machine.
- **An AI agent that uses your real tools (Pro).** `highhx agent` works through HighhX's
  own commands and safety system — not a chatbot pasting shell snippets.
- **Detects instead of asking.** Python (pip/uv/poetry/pdm/pipenv), Node (npm/pnpm/yarn/bun),
  React, Next.js, Flutter/Dart, Java (Maven/Gradle), C/C++ (CMake/Make), Go, Rust, Docker,
  common databases and monorepos — from real manifests and lockfiles, not file extensions.
- **Safe by default.** Commands are classified as safe, normal, dangerous or critical.
  `git push`, `rm -rf`, `DROP TABLE`, production deploys and restores need approval;
  `--dry-run` previews anything; policies can make approvals non-bypassable even with `--yes`.
- **A real workflow engine.** YAML workflows with dependency graphs, parallel execution,
  conditions, variables, retries with backoff, timeouts, approvals and reusable workflows —
  validated before anything runs.
- **Scriptable.** Every command supports `--json` and meaningful exit codes.

## Installation

HighhX needs Python 3.11+. It is developed and tested on macOS; Linux and Windows
support is designed in (see [docs/development.md](docs/development.md#platform-support))
but not yet verified on those systems.

> HighhXcli is **not yet published on PyPI**. Install it from a built wheel or from source.

```bash
# from a checkout of this repository
python -m pip install build && python -m build          # creates dist/highhxcli-*.whl
pipx install dist/highhxcli-*.whl                       # or: pip install dist/highhxcli-*.whl

# development install
python -m venv .venv && . .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

Both `highhx` and `highhxcli` are installed as commands, and `python -m highhx` works too.

Runtime dependencies are deliberately small: `click`, `rich` and `PyYAML`.
External tools (git, docker, kubectl, psql …) are used only when a feature needs them.

## Quick start

```bash
cd your-project
highhx init            # detect the project, create .highhx/ (never overwrites without --force)
highhx doctor          # check tools, config, env vars, ports
highhx status          # dashboard: git, environment, services, recent runs
highhx test            # auto-detected test runner (pytest, vitest, jest, flutter, mvn, …)
highhx run ci          # run a workflow; parallel where dependencies allow
highhx run ci --dry-run
highhx history         # what ran, when, how long, exit codes
highhx logs            # output of the last execution (secrets redacted)
```

`highhx init` creates:

```text
.highhx/
├── config.yaml          # commands, services, deploy targets, approvals …
├── environment.yaml     # declared variables and profiles (values live in .env files)
├── policies.yaml        # protected branches, forbidden files, rules
├── workflows/           # dev, test, build, ci, release, deploy, rollback
├── hooks/               # scripts for git hooks
├── state/               # local database (git-ignored)
└── logs/                # execution logs (git-ignored)
```

## The interactive session

`highhx` with no arguments, in a terminal, opens the HighhX session (`highhx agent` opens the
same one). Outside a terminal, and with `--json` or `--quiet`, it prints the help as before,
so scripts and CI are unaffected.

```text
$ highhx

  (the Knight)   HighhX v0.4.0
                 Developer command center
                 ~/code/shop
                 main • clean
                 Free • Local

❯ show git status

◉ highhx git status
✓ Working tree clean
✓ highhx git status (0.1s)

❯ Fix the failing tests

╭─ HighhX Pro capability ─────────────────────────────╮
│  AI code changes require HighhX Pro.                │
│                                                     │
│  Available locally, without AI:                     │
│  1  Run the tests         highhx test               │
│  2  Diagnose the project  highhx diagnose           │
│  3  Show recent logs      highhx logs               │
│                                                     │
│  [1-3] Continue locally    [p] View Pro             │
╰─────────────────────────────────────────────────────╯
```

- **Plain language first.** On Free, requests that map to a known action (*run the tests*,
  *run the checks*, *build*, *show git status*, *security scan*, *open localhost:3000* …)
  run the matching HighhX command — deterministically, no AI. Requests that need
  understanding name the Pro capability they need and offer the local commands that can
  do part of the job. On Pro the AI agent handles every request.
- **`!command`** runs a shell command through the HighhX engine (risk classification,
  policy, approval, history); **`highhx <command>`** runs any HighhX command in the session.
- **Input.** ↑/↓ history (kept across sessions), line editing, `\` at the end of a line or
  a `"""` block for multi-line input, Ctrl+C interrupts the running request, Ctrl+D exits.
- **Status line.** `Free • Local`, `Free • Connected`, `Pro • Connected`,
  `Pro • Offline (cached)` or `… • Platform unavailable`. Only a live answer from the
  platform attaches the AI agent. When the platform cannot be reached, local capabilities
  keep working and the session re-checks when a request needs the agent; if the gateway
  fails during a Pro request, the session says so and offers the local route for it.
- **Deterministic means predictable.** Free never calls a model or reads a provider API key.
  File names are never treated as websites (`open main.py` is not `https://main.py`), and
  known requests that change files (`fix`, `install dependencies`) ask first.
- **Plan changes apply in place.** Run `highhx login` (or `/account` after upgrading) inside
  the session and it re-checks your account: the AI agent attaches when the platform grants
  it, and detaches when it no longer does.
- **Slash commands.** `/help` `/status` `/tools` `/context` `/config` `/account` `/usage`
  `/history` `/memory` `/pro` `/clear` `/quit`, plus the agent's `/plan` `/model` `/mode`
  `/changes` `/undo` (Pro).

## HighhX Pro: the AI developer agent

```text
$ highhx

     ▗█▖
     ▐▀▌
    ▗ ▄ ▖
   ▗▚▐█▌▞▖
  ▗▚█▐█▌█▞▖      HighhX v0.4.0
   ▟█▐█▌█▙       Developer command center
  ▐▐█▌█▐█▌▌      ~/code/shop
  █▗▜▌█▐▛▖█      main • clean
  █▐▙▘█▝▟▌█      Pro • Connected
  ▐▐▜▌▄▐▛▌▌
 ▗▝▐▐▌█▐▌▌▘▖
 █▙▝█▌█▐█▘▟█
▜▙▜█▖▘█▝▗█▛▟▛
 ▀█▟▀ █ ▀▙█▀
   ▀▌ █ ▐▀

Project   shop Python, FastAPI
AI        Connected HighhX (managed)

What would you like me to do? (/help for commands)

❯ run all the tests and fix whatever fails

╭─ Plan ───────────────────────────────────────────╮
│  1. Run the test suite                           │
│  2. Investigate the failures                     │
│  3. Fix the root cause                           │
│  4. Re-run tests, lint and type checks           │
╰─ Get the test suite green ───────────────────────╯
Proceed? [Y/n]

✓ Run tests — 3 tests failing (4.1s)
✓ Read src/shop/cart.py — 88 lines

╭─ ⚠ Action requires approval ─────────────────────╮
│  Edit src/shop/cart.py (+2 -1)                   │
╰──────────────────────────────────────────────────╯
  …diff…
Proceed? [y/N/a=always this session] y
✓ Edit src/shop/cart.py — +2 -1
✓ Run tests — Tests passing — 48 passed (pytest) (4.3s)
✓ Run checks — all checks passed

Fixed the discount rounding in `cart.total()` (it rounded before applying tax).
All 48 tests pass; lint and type checks are clean.

4 steps  ·  1 file changed (/undo)  ·  38.2k tokens  ·  41s
```

Ask for what you want in plain language — *explain how this project works*, *find and
fix the bugs*, *add authentication*, *find security issues*, *why is the application
crashing?*, *prepare this project for release*, *deploy this*. The agent inspects the
project, proposes a plan for multi-step work, uses HighhX's capabilities as tools
(code search and edits, tests, checks, fixers, builds, dependencies, git, security scans,
doctor/diagnose/repair, workflows, deploy and rollback), verifies what it did and
summarises it.

- **Same safety system.** Commands run through the HighhX engine: risk classification,
  `policies.yaml`, approvals and history. File edits show a diff and ask (unless you
  choose `--mode auto-edit`); pushes, deploys and rollbacks always ask; production
  deploys need typed confirmation. The agent cannot leave the project, read secret files
  or touch `.git/`. `--mode read-only` investigates without changing anything.
- **Slash commands.** Everything from the [interactive session](#the-interactive-session), plus
  `/plan` `/model` `/mode` `/changes` `/undo`.
- **Sessions.** Saved per project: `highhx agent --continue`, `--resume ID`, `highhx agent sessions`.
- **Scriptable.** `highhx agent "…"` outside a terminal (or with `--json`) handles one request
  and exits — `--yes --mode auto-edit` for unattended runs in CI.
- **Providers.** All Pro AI goes through the HighhX platform (authenticated, plan-checked,
  metered); choose the upstream — Anthropic, OpenAI or Gemini — with `highhx account settings`
  or `/model`. No provider key is needed on your machine.
- **Kill switch.** `highhx agent stop` (or Ctrl+C) cancels the model request, retries, running
  commands and their child processes immediately.
- **Computer use.** The agent observes browsers and apps semantically and chooses among valid
  actions; see [docs/computer-use.md](docs/computer-use.md).

```bash
highhx login                 # browser sign-in (creates your account)
highhx account upgrade       # HighhX Pro checkout
highhx                       # interactive session (also: highhx agent)
highhx agent "why is the application crashing?"
```

Guides: [docs/agent.md](docs/agent.md) · [docs/computer-use.md](docs/computer-use.md) · [docs/platform.md](docs/platform.md).

## Commands

Full reference with every option: [docs/commands.md](docs/commands.md).

| Area | Commands |
|---|---|
| HighhX Pro | `agent` `agent sessions` `agent models` `agent stop` |
| Automation (no AI) | `do` `computer status/open/observe/click/type/select/press/scroll/run` `computer browser start/stop` |
| Account | `login` `logout` `account` `account plans/usage/upgrade/billing/settings` |
| Project | `init` `status` `info` `dev` `start` `stop` `restart` `check` |
| Code & tasks | `run <workflow>` `exec <command>` `script <name>` `task <name>` `watch` `fix` |
| Dependencies | `deps` `deps install` `deps update` `deps outdated` `deps audit` `deps clean` |
| Testing & build | `test [--watch] [--coverage] [--changed]` `benchmark` `build` `clean` `package` `artifacts` |
| Environment | `env` `env check` `env set` `env profile` `env diff` |
| Git & releases | `git status/diff/branch/commit/sync/tag/history` `version` `changelog` `release` `publish` |
| Deployment | `deploy [target]` `deploy status` `deploy logs` `rollback` `environments` |
| Security | `security` `security scan/secrets/deps/config/report` |
| Containers & data | `docker up/down/logs` `services` `ports` `db status/migrate/seed/backup/restore` |
| Workflows & automation | `workflow list/validate/create/graph` `schedule` `hook` `trigger` `watchers` |
| Observability | `logs [--follow]` `history [id]` `audit` `report` `trace` |
| Extensibility & team | `plugin list/install/remove/update/search/trust` `config` `policy` `workspace` `profile` |
| Diagnostics | `doctor` `diagnose` `repair` `debug` |

Global options (work before or after the command): `--json`, `--dry-run`, `--yes/-y`,
`--force`, `--quiet/-q`, `--verbose/-v`, `--debug`, `--no-color`, `--cwd/-C DIR`,
`--config-profile NAME`, `--version`, `--help`.

A few examples:

```bash
highhx exec -- pytest -q                 # run anything with env profile, risk check, history
highhx exec --timeout 30s --retry 3 -- ./flaky.sh
highhx test --changed                    # only tests related to files changed since HEAD
highhx deps update                       # shows what will change, then asks
highhx env set DATABASE_URL              # prompts without echo; value never printed again
highhx release                           # version from Conventional Commits, changelog, tag
highhx deploy staging --version 1.4.0    # preflight → approval → deploy → health check
highhx rollback staging                  # restore the previous successful deployment
highhx security --fail-on high           # exit 9 if high/critical findings
highhx workflow graph ci --format mermaid
highhx status --json | jq .git.branch
```

## Workflows

Workflows are YAML files in `.highhx/workflows/`. Full reference:
[docs/workflows.md](docs/workflows.md) · JSON Schema: [schemas/workflow.schema.json](schemas/workflow.schema.json).

```yaml
name: production

settings:
  fail_fast: true
  max_parallel: 4
  timeout: 30m

steps:
  - id: test
    run: pytest

  - id: lint
    run: ruff check .

  - id: build
    run: docker build -t myapp .
    depends_on: [test, lint]          # test and lint run in parallel first

  - id: deploy
    run: ./deploy.sh ${{ steps.build.outputs.tag }}
    depends_on: [build]
    approval: true                    # asks before running
    retry:
      attempts: 3
      delay: 10s                      # exponential backoff: 10s, 20s …

  - id: notify
    run: ./notify.sh "deploy failed"
    depends_on: [deploy]
    if: failure()
```

A step never starts before every step in its `depends_on` succeeded. Steps whose
dependencies are satisfied run in parallel (up to `max_parallel`). Also supported:
`if:` conditions, `${{ }}` variables (`env`, `vars`, `inputs`, `steps.<id>.outputs`),
step outputs, `continue_on_error`, per-step `timeout`/`cwd`/`env`, reusable workflows
(`uses: other-workflow` with `with:` inputs), and `on:` event triggers.

`highhx workflow validate` catches circular and missing dependencies, duplicate ids,
unknown fields, bad expressions, references to steps that are not dependencies,
unparsable commands, impossible steps and risky commands without `approval` —
before anything runs.

## Configuration

`.highhx/config.yaml` is validated strictly (unknown keys are errors with
"did you mean" suggestions). Reference: [docs/configuration.md](docs/configuration.md) ·
JSON Schema: [schemas/config.schema.json](schemas/config.schema.json).

```yaml
version: 1
project:
  name: shop
commands:              # override anything HighhX detected
  test: uv run pytest
  dev: uv run uvicorn app.main:app --reload
services:              # highhx start / stop / services
  api:
    command: uv run uvicorn app.main:app --port 8000
    port: 8000
    health: {url: http://127.0.0.1:8000/health}
deploy:
  default: staging
  targets:
    staging:
      type: ssh                       # local | docker | ssh | kubernetes | terraform | plugin:<name>
      host: deploy@staging.example.com
      command: ./deploy.sh {{ version }}
      rollback_command: ./deploy.sh {{ previous_version }}
      health_check: {url: https://staging.example.com/health}
approvals:
  auto_approve: normal                # never prompt at or below this risk
  yes_max_risk: critical              # the highest risk --yes may approve
```

Config profiles (`.highhx/profiles/ci.yaml`) overlay the config with `--config-profile ci`.
Environment profiles (development/staging/production) are separate and live in
`.highhx/environment.yaml` plus your `.env` files — see `highhx env --help`.

## Plugins

Plugins add commands, workflows, templates, detectors and deployment backends.
Guide: [docs/plugins.md](docs/plugins.md).

```yaml
# my-plugin/highhx-plugin.yaml
name: greet
version: 1.0.0
api_version: 1
permissions: [commands]
contributes:
  commands:
    - name: greet
      run: echo "hello"
  workflows: [workflows]
```

```bash
highhx plugin install ./my-plugin      # or a git URL, or a name from plugins.index
highhx greet
```

Declarative contributions run as subprocesses with an isolated environment.
Python code plugins run only when `plugins.allow_code: true` **and** you trusted those
exact files (by SHA-256) with `highhx plugin install` or `highhx plugin trust`. Trust is
stored in your user data directory, so a cloned repository cannot enable its own plugin code.

## Security model

Details: [docs/security.md](docs/security.md).

- **Approvals.** Every command is classified (safe / normal / dangerous / critical).
  Anything above `approvals.auto_approve` asks; critical actions require typing a word.
  Without a terminal, HighhX denies instead of guessing. `--yes` approves up to
  `approvals.yes_max_risk`, never beyond, and never for non-bypassable rules
  (e.g. `rm -rf /`, `terraform destroy`, policy rules with `bypassable: false`).
- **Policies.** `.highhx/policies.yaml` can deny commands/actions, require approval,
  protect branches, forbid committed files and require a clean tree for releases/deploys.
- **Secrets.** Secret values are never printed: `env` masks them, logs and history are
  redacted (known secret values plus token patterns), and `security secrets` reports
  file/line/type only. New `.env` files get owner-only permissions and are git-ignored.
- **The agent.** Uses the same engine, policies and approvals as you do, plus path
  confinement, secret-file protection and redaction of everything sent to the model.
  Agent actions have policy names (`agent:write`, `agent:exec`, `agent:deploy:<target>` …)
  so `policies.yaml` can restrict or forbid them.
- **No claims.** `highhx security` reports concrete findings from local checks. An empty
  report does not mean a project is secure, and HighhX never says it is.

Report vulnerabilities in HighhX itself as described in [SECURITY.md](SECURITY.md).

## Development

```bash
pip install -e ".[dev]" -e "./server[dev]"
pytest                 # CLI: unit, integration, security and end-to-end tests
(cd server && pytest)  # platform API + live CLI ↔ platform integration tests
ruff check . && ruff format --check .
mypy                   # strict typing of src/highhx
```

The HighhX Platform backend lives in [`server/`](server/README.md).

Architecture: [docs/architecture.md](docs/architecture.md) · Development guide:
[docs/development.md](docs/development.md) · Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md).

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
[Code of Conduct](CODE_OF_CONDUCT.md). Please open an issue before large changes.

## License

MIT — see [LICENSE](LICENSE).
