Skip to content

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.

Inputs

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.