> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/hybrid-hivel-agent/4.-commands-and-workflow/commands-reference.md).

# Commands reference

hivel-agent is a single binary with several subcommands. sync is the everyday command (download plus upload in one step); download and send let you split that into two steps for review; validate and config check are pre-flight checks; work-metrics is a separate, optional job on its own schedule. Flags below are grouped by which command they apply to.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Command</strong></td><td><strong>What it does</strong></td></tr><tr><td>version</td><td>Print version, build date, harvest library version</td></tr><tr><td>sync</td><td>Download from sources + upload to Hivel (full pipeline)</td></tr><tr><td>download</td><td>Pull from sources to disk only - no upload</td></tr><tr><td>send</td><td>Upload an existing on-disk snapshot - skip source pull</td></tr><tr><td>validate</td><td>Check connectivity to configured providers + Hivel, then exit</td></tr><tr><td>config check</td><td>Validate config file syntax and required fields</td></tr><tr><td>config fields</td><td>List all Jira fields for your instance</td></tr><tr><td>work-metrics</td><td>Classify unprocessed commits/PRs (rework/newwork/maintenance/assistance) and upload results - separate cron schedule from sync</td></tr></tbody></table>

***Global flags (all commands)***

| **Flag**                  | **Description**                          |
| ------------------------- | ---------------------------------------- |
| --config /path/config.yml | Path to config file (required)           |
| --env-file /path/.env     | Load credentials before config expansion |

\
***Sync flags***

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Flag</td><td>Description</td></tr><tr><td>--provider &#x3C;name></td><td>jira, github, gitlab, bitbucket, azure, claudeotel or all (default)</td></tr><tr><td>--project &#x3C;KEY></td><td>Jira only - sync a single project key</td></tr><tr><td>--verbose</td><td>Enable debug logging</td></tr><tr><td>--debug-requests</td><td>Dump HTTP traffic to debug.log</td></tr><tr><td>--dry-run</td><td>Download without uploading</td></tr><tr><td>--no-progress</td><td>Disable TUI/progress bars</td></tr><tr><td>--tui</td><td>Force TUI even when not in a terminal</td></tr><tr><td>--no-override-config</td><td>Skip server-side SCM config fetch; use only local config.yml values (GitHub only)</td></tr></tbody></table>

\
***Download flags***

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Flag</strong></td><td><strong>Description</strong></td></tr><tr><td>--output-dir /path</td><td>Directory to write snapshot to (required)</td></tr><tr><td>--provider &#x3C;name></td><td>Same as sync</td></tr><tr><td>--project &#x3C;KEY></td><td>Jira only</td></tr><tr><td>--verbose</td><td>Debug logging</td></tr><tr><td>--debug-requests</td><td>Dump HTTP traffic</td></tr><tr><td>--no-progress</td><td>Disable TUI</td></tr><tr><td>--no-override-config</td><td>Skip server-side SCM config fetch; use only local config.yml values (GitHub only)</td></tr></tbody></table>

***Send flags***

| **Flag**          | **Description**                                    |
| ----------------- | -------------------------------------------------- |
| --input-dir /path | Directory containing snapshot to upload (required) |
| --no-progress     | Disable TUI                                        |

***Validate flags***

| **Flag**           | **Description**                                                                         |
| ------------------ | --------------------------------------------------------------------------------------- |
| --provider \<name> | Validate only this provider                                                             |
| --instance \<slug> | Jira only - validate only this instance\_slug (default: every configured Jira instance) |

**Work-metrics flags**

Fetches a queue of commits/PRs still needing rework/newwork/maintenance/assistance classification from Hivel, classifies them via GitHub/GitLab/Bitbucket/Azure DevOps, and uploads results. Requires at least one of github:, gitlab:, bitbucket:, or azure: configured - not Jira/Cursor. Run this on its own cron schedule, separate from sync.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Flag</strong></td><td><strong>Description</strong></td></tr><tr><td>--limit &#x3C;n></td><td>Max commits/PRs to fetch and process this run (default: 100)</td></tr><tr><td>--rework-days &#x3C;n></td><td>Override the org's configured rework window in days</td></tr><tr><td>--time-budget &#x3C;duration></td><td>Stop classifying and ship whatever's done once elapsed (default: 50m) - keeps a run from overlapping the next scheduled one</td></tr><tr><td>--output-dir /path</td><td>Write results here instead of uploading (download only)</td></tr><tr><td>--dry-run</td><td>Classify and print results without writing files or uploading</td></tr><tr><td>--verbose</td><td>Debug logging</td></tr></tbody></table>

Azure DevOps and Bitbucket Cloud both have no blame REST API, so their commits are classified via a local git clone (clone\_cache\_dir/clone\_mode/clone\_depth/clone\_since\_days - same settings under both the azure: and bitbucket: sections below). Azure's merged PRs are also classified this way (no PR-diff API either). GitHub/GitLab classify entirely via their own APIs and never touch disk.

If an Azure PR's merge commit can't be resolved from that local clone, it is not assumed to be gone - the shallow clone window aging out an old commit looks identical to a genuinely deleted one. The agent double-checks via Azure's own commit API before ever marking a PR permanently done; anything short of a confirmed 404 just retries on the next scheduled run.

\
**Examples**

```
# Validate connectivity
./hivel-agent --config config.yml --env-file .env validate
 
# Full sync
./hivel-agent --config config.yml --env-file .env sync
 
# Download to disk, review, then send
./hivel-agent --config config.yml --env-file .env download --output-dir /tmp/snapshot
./hivel-agent --config config.yml --env-file .env send --input-dir /tmp/snapshot
 
# Pre-flight config check
./hivel-agent --config config.yml --env-file .env config check
 
# Classify unprocessed commits/PRs and upload (run on its own cron schedule)
./hivel-agent --config config.yml --env-file .env work-metrics
```

{% columns %}
{% column %} <a href="/hybrid-hivel-agent/4.-commands-and-workflow.md" class="button primary" data-icon="backward">Commands & Workflow</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/hybrid-hivel-agent/4.-commands-and-workflow/credentials-required-per-command.md" class="button primary" data-icon="forward">Credentials required</a>
{% endcolumn %}
{% endcolumns %}