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.
Command
What it does
version
Print version, build date, harvest library version
sync
Download from sources + upload to Hivel (full pipeline)
download
Pull from sources to disk only - no upload
send
Upload an existing on-disk snapshot - skip source pull
validate
Check connectivity to configured providers + Hivel, then exit
config check
Validate config file syntax and required fields
config fields
List all Jira fields for your instance
work-metrics
Classify unprocessed commits/PRs (rework/newwork/maintenance/assistance) and upload results - separate cron schedule from sync
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
Flag
Description
--provider <name>
jira, github, gitlab, bitbucket, azure, claudeotel or all (default)
--project <KEY>
Jira only - sync a single project key
--verbose
Enable debug logging
--debug-requests
Dump HTTP traffic to debug.log
--dry-run
Download without uploading
--no-progress
Disable TUI/progress bars
--tui
Force TUI even when not in a terminal
--no-override-config
Skip server-side SCM config fetch; use only local config.yml values (GitHub only)
Download flags
Flag
Description
--output-dir /path
Directory to write snapshot to (required)
--provider <name>
Same as sync
--project <KEY>
Jira only
--verbose
Debug logging
--debug-requests
Dump HTTP traffic
--no-progress
Disable TUI
--no-override-config
Skip server-side SCM config fetch; use only local config.yml values (GitHub only)
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.
Flag
Description
--limit <n>
Max commits/PRs to fetch and process this run (default: 100)
--rework-days <n>
Override the org's configured rework window in days
--time-budget <duration>
Stop classifying and ship whatever's done once elapsed (default: 50m) - keeps a run from overlapping the next scheduled one
--output-dir /path
Write results here instead of uploading (download only)
--dry-run
Classify and print results without writing files or uploading
--verbose
Debug logging
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
Last updated