# HiveOS Trace CLI Quickstart

`hiveos-trace` is a standalone CLI wedge extracted from HiveOS tracing concepts.
It is built for operators and developers who want execution visibility, replay, and diagnosis without adopting the full HiveOS platform runtime.

## Install

```powershell
pipx install hiveos-trace
```

Alternative:

```powershell
python -m pip install -U hiveos-trace
```

From source:

```powershell
python -m pip install -e .
```

If `hive` is not recognized in your shell, use module form:

```powershell
python -m hiveos.hive --help
python -m hiveos.hive trace ls
```

## Zero-to-One

```powershell
hive doctor
hive quickstart --no-open
hive trace ls --limit 5
```

## CLI Surface (v0.1.6)

Top-level:

```powershell
hive --help
hive --version
hive quickstart [--open] [--no-open] [--ui-url <url>]
hive doctor [--ui-url <url>]
```

Trace commands:

```powershell
hive trace run [--name <label>] [--cwd <path>] [--timeout-sec <sec>] [--open] [--no-open] [--ui-url <url>] [--proxy] [--proxy-upstream <url>] [--proxy-port <port>] -- <command...>
hive trace replay <run_id> [--name <label>] [--cwd <path>] [--timeout-sec <sec>] [--open] [--no-open] [--ui-url <url>]
hive trace ls [--limit <n>] [--status <status>] [--json]
hive trace show <run_id> [--limit <n>] [--json]
hive trace tail [--run-id <id>] [--limit <n>] [--follow] [--json]
hive trace export <run_id> --bundle <path>
hive trace import --bundle <path> [--as-run-id <id>]
hive trace summary <run_id> [--event-limit <n>] [--tail-lines <n>] [--json]
hive trace diff <run_id_a> <run_id_b> [--event-limit <n>] [--tail-lines <n>] [--json]
hive trace diagnose <run_id> [--event-limit <n>] [--tail-lines <n>] [--json]
hive trace open <run_id> [--ui-url <url>]
hive trace archive <run_id> [--reason <text>] [--actor <label>]
hive trace unarchive <run_id>
hive trace prune --older-than <window> [--include-active] [--drop-events]
hive trace reconcile [--stale-after <window>] [--json]
```

`hive trace ls --status` values: `all | active | archived | running | success | failed`

Full release reference: `docs/releases/hiveos-trace-command-reference-v0.1.6.md`

## Open Behavior

- `quickstart`, `trace run`, and `trace replay` default to no-open.
- Use `--open` to explicitly open UI for a run.
- `--no-open` always forces no-open.
- If `--open` is requested and the UI target is unavailable, Hive serves a local fallback run page.
- Set `HIVE_TRACE_OPEN_ON_RUN=true` if you want default-open behavior globally.

## What This Gives You

- Run-level event lineage (`observe_run_started`, `observe_run_finished`)
- Step/output event capture from wrapped commands
- Checkpoint/rerun intent events for SDK-based flows
- Fast operator loop:
  - run (`trace run`)
  - summarize (`trace summary`)
  - tail (`trace tail`)
  - inspect (`trace show`)
  - compare (`trace diff`)
  - replay (`trace replay`)
  - diagnose (`trace diagnose`)
- Lifecycle hygiene (`archive`, `unarchive`, `prune`, `reconcile`)
- Team handoff path (`export`, `import`)

Run records are stored under `~/.hiveos-trace/runs`.
Default trace log path is `~/.hiveos-trace/logs/trace_events.log` unless overridden.

## SDK Integration (Optional)

```python
from hiveos.observe import observe_run, observe_step

def my_pipeline():
    with observe_run("daily-sync", metadata={"team": "platform"}) as run_id:
        observe_step(run_id, "extract.start", payload={"source": "s3"})
        observe_step(run_id, "extract.finish", payload={"rows": 1203})
```

Checkpoint + rerun intent:

```python
from hiveos.observe import observe_checkpoint, observe_rerun_request

observe_checkpoint(run_id, "ckpt-42", step_name="extract.finish", state_ref="state://pipeline/extract/42")
observe_rerun_request(run_id, from_checkpoint_id="ckpt-42", reason="retry with override")
```

## Proxy Capture Mode (Optional)

```powershell
hive trace run --proxy -- python agent.py
hive trace run --proxy --proxy-upstream https://api.openai.com/v1 -- python agent.py
```

## Share Runs Across Machines

Export a run:

```powershell
hive trace export <run_id> --bundle .\trace-bundles\run.bundle.json
```

Import on another machine:

```powershell
hive trace import --bundle .\trace-bundles\run.bundle.json
```

If the same run id already exists, remap during import:

```powershell
hive trace import --bundle .\trace-bundles\run.bundle.json --as-run-id observe-run:shared-001
```

## Release Validation

Before public release:
1. Run `.github/workflows/hive-trace-publish-testpypi.yml` (manual dispatch).
2. Validate clean install from TestPyPI.

```powershell
pipx install --pip-args="--index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple" hiveos-trace
hive doctor
hive quickstart --no-open
```

Production release:
- Push tag format `hiveos-trace-v<version>` (example: `hiveos-trace-v0.1.6`) to trigger `.github/workflows/hive-trace-publish-pypi.yml`.
