CLI reference
This page lists every command and flag of the dvforge CLI, with defaults,
environment variables, and exit codes. It follows the grouping of
dvforge upload --help. For explanations and examples, see
The dvforge CLI.
Commands
| Command |
What it does |
dvforge upload |
Uploads one regression: JUnit results become jobs, matched logs are uploaded. Safe to rerun; rerunning the same command resumes an interrupted upload. |
dvforge --version |
Prints the CLI version, for example dvforge 0.1.0. |
dvforge --help |
Lists the commands. |
dvforge upload --help |
Lists every upload flag. |
dvforge upload
dvforge upload [--url URL] [--token TOKEN] [--project ORG/SLUG]
--name NAME --external-id ID [--branch B] [--rev SHA]
[--rev-order N] [--scm {git,p4,svn,hg}]
[--build-target T] [--ci-provider P] [--ci-url URL]
--junit FILE [--logs GLOB] [--only-failing-logs]
[--no-logs] [--simulator S] [--max-log-mb MB]
[--batch-size N] [--concurrency N] [--no-complete]
[--wait] [--wait-timeout SEC] [--dry-run]
--name, --external-id, and --junit are required.
Connection
| Flag |
Default |
Meaning |
--url URL |
$DVFORGE_URL, else http://localhost:8000 |
Where to upload: https://api.daruur.cloud, or your data plane's URL. Must start with http:// or https://. |
--token TOKEN |
$DVFORGE_TOKEN |
Project token (dvf_…) with the ingest:write scope. Prefer the environment variable: flags are visible in ps. |
--project ORG/SLUG |
$DVFORGE_PROJECT |
Target project, as org-slug/project-slug. Optional with a project token; if set, it must name the token's project. |
Regression
| Flag |
Default |
Meaning |
--name NAME |
required |
Display name, for example nightly 1234. Up to 255 characters. Uploading again with a new name renames the regression. |
--external-id ID |
required |
Stable id for this regression, for example the CI build id. Uploads with the same id go into the same regression. Up to 255 characters. |
--branch B |
none |
Branch name. Up to 255 characters. Used by the branch filter, branch-scoped triage rules, and the recurred badge. |
--rev SHA |
none |
SCM revision: a commit SHA or changelist. Up to 128 characters. |
--rev-order N |
none |
Integer that increases with each revision, such as a Perforce changelist or a git commit count. |
--scm {git,p4,svn,hg} |
none |
Version control system. |
--build-target T |
none |
Default build target for jobs whose JUnit doesn't name one. Up to 255 characters. |
--ci-provider P |
none |
CI system label, for example github, gitlab, or jenkins. Up to 64 characters. |
--ci-url URL |
none |
Link back to the CI run, shown as CI build on the regression page. Must start with http:// or https://. Up to 2,048 characters. |
| Flag |
Default |
Meaning |
--junit FILE |
required |
JUnit XML results. Repeat for several files; all go into one regression. |
--logs GLOB |
none |
Log files to match to tests, for example 'out/**/*.log'. Repeatable. Quote the pattern. A directory means every file under it. |
--only-failing-logs |
off |
Upload logs only for jobs that didn't pass (fail, error, timeout, killed). |
--no-logs |
off |
Send results only. Ignores all logs, including log pointers in the JUnit. Can't be combined with --logs or --only-failing-logs. |
--simulator S |
none |
Simulator name for jobs whose JUnit doesn't name one. Recorded only; it doesn't choose the log parser. |
--max-log-mb MB |
256 |
Skip, with a warning, logs larger than this many MiB uncompressed. At least 1. |
Behaviour
| Flag |
Default |
Meaning |
--batch-size N |
5000 |
Jobs per request, from 1 to 5,000. |
--concurrency N |
8 |
Logs hashed and uploaded in parallel, from 1 to 64. |
--no-complete |
off |
Leave the regression live after the upload, because more uploads for it are coming. |
--wait |
off |
Wait until DV Forge has processed every batch. Exits 4 if a batch fails to process. |
--wait-timeout SEC |
600 |
How long --wait waits, in seconds. Must be positive. Exits 4 when exceeded. |
--dry-run |
off |
Print every request the upload would make, and send nothing. Needs no token. |
Environment variables
| Variable |
Equivalent flag |
Notes |
DVFORGE_URL |
--url |
Defaults to http://localhost:8000 when neither is set. |
DVFORGE_TOKEN |
--token |
The recommended way to pass the token. Never printed. |
DVFORGE_PROJECT |
--project |
Rarely needed with a project token. |
TMPDIR |
— |
Standalone binary only: where it unpacks itself at start-up (default /tmp). Point it at a directory that allows execution if /tmp is mounted noexec. |
A flag always overrides its environment variable. A real upload needs a token;
--dry-run needs neither a token nor a project.
Output
- stdout: the summary (or, with
--dry-run, the planned requests).
- stderr: progress (
batch 1/3: …), warnings, and errors, each prefixed
with dvforge:.
Warnings don't change the exit code:
| Warning |
Meaning |
--logs '…' matched no files |
A --logs pattern found nothing. |
<test>: ambiguous log match (…); no log attached |
Several files matched a test equally well. At most five are listed, then a count. |
skipping <file>: N MiB exceeds --max-log-mb M |
The log is over the size limit. |
skipping unreadable log <file>: … |
The log couldn't be read or isn't valid gzip. |
--wait skips N batch(es) the data plane spooled; … |
The data plane queued some batches; --wait can't follow them. |
Exit codes
| Code |
Meaning |
0 |
Success, including --dry-run, and uploads a data plane queued while DV Forge was unreachable. |
2 |
Usage error: bad or conflicting flags, an out-of-range value, a missing or unreadable JUnit file, malformed XML or XML with a DOCTYPE/ENTITY declaration, no <testcase> elements, or no credentials. Nothing was sent. |
3 |
Authentication or permission error (HTTP 401 or 403): a bad, expired, revoked, or read-only token; or a project that must upload through a different URL (direct upload to a project bound to a data plane, or a data plane that doesn't serve the project). |
4 |
Server or network error after five attempts, any other API error, a batch that failed to process, or a --wait timeout. Rerun the same command to resume. |
130 |
Interrupted with Ctrl-C. Rerun the same command to resume. |