rad remote commands

Use rad remote to submit and manage hosted mutation runs.

All commands require RADFORGE_API_TOKEN. They use RADFORGE_REMOTE_URL unless you provide --endpoint <url>. Add --json to request indented JSON.

Command	Required options	Result
rad remote run --artifact <plan-path>	--artifact	Submits a plan and tracked source snapshot. Add --wait to wait.
rad remote status --run <run-id>	--run	Returns the run and every attempt.
rad remote findings --run <run-id>	--run	Returns survivor and coverage-gap findings.
rad remote accept --run <run-id> --finding <finding-id> --reason <reason>	--run, --finding, --reason	Records a reviewed survivor in radforge-waivers.json.
rad remote cancel --run <run-id> --attempt <attempt-id> --reason <reason>	--run, --attempt, --reason	Requests cancellation of the active attempt.
rad remote retry --run <run-id>	--run	Creates an attempt from the original plan and source snapshot.
rad remote doctor	None	Checks authentication, compatibility, profiles, and upload limits.

Submit a run

Create a plan, verify hosted access, and submit the plan:

rad plan --target src/example.ts --json > plan.json
rad remote doctor
rad remote run --artifact plan.json

Add --wait --timeout 10m when a script needs the terminal run state. Waiting returns exit status 0 only for succeeded_with_findings or succeeded_without_findings; other terminal states return 1.

remote run uploads the JSON plan and a final-state snapshot of files tracked by Git. The snapshot includes local staged and unstaged contents, executable mode, and safe relative symlinks. A tracked file deleted from the working tree is absent. Untracked files, special files, and paths outside the repository are never included. Radforge rejects a plan that names an untracked or deleted source file.

Newly generated hosted plans contain the digest of the source manifest used during planning. The CLI asks the authenticated repository which file blobs it already recognizes and uploads only missing file bytes in bounded packs. The server then creates one checksum-verified compressed archive for the hosted worker. A digest from another repository does not grant reuse or reveal whether that content exists.

An older saved plan without source-manifest metadata uses the compatible full archive path. The same fallback applies when the server does not advertise the manifest protocol or explicitly reports that the protocol is unavailable. Authentication, authorization, integrity, limit, and service failures do not fall back. Generate a new plan to use incremental transfer.

Where enabled by the server, the CLI sends plans, source archives, and missing blob packs directly to object storage using short-lived upload URLs. The server verifies each staged upload before returning a usable artifact. The CLI does not forward your Radforge API token to storage.

Direct-upload compatibility is separate from incremental source transfer. If upload initiation explicitly reports an unsupported endpoint (404 or 501), the CLI sends the bytes through the authenticated API instead. A failed storage upload or finalization does not trigger that fallback. An already completed initiation returns its verified result without uploading the bytes again.

The current source limits are 100,000 tracked entries, 256 MiB per file, 2 GiB expanded, 4,096 bytes per path, and 64 path segments. The server advertises its plan, archive, manifest, pack, and batch limits through rad remote doctor. The smaller applicable client or server limit wins.

Git submodules are unsupported and stop submission with an error. Git LFS pointer files are uploaded as the bytes currently present in the working tree; the CLI does not download LFS objects. Dangling, cyclic, absolute, and repository-escaping symlinks are rejected. If tracked contents change while a hosted plan is generated, the CLI retries planning and capture once, then stops without uploading if the repository changes again.

Check a run

rad remote status --run <run-id>
rad remote findings --run <run-id>

Status returns successfully even when the run state reports a failure. Inspect the run state before reading findings.

Cancel an attempt

Provide a reason when you cancel the active attempt:

rad remote cancel --run <run-id> --attempt <attempt-id> --reason "Superseded by a new commit"

The reason must be one line and at most 512 characters after surrounding whitespace is removed. If the attempt has already finished, cancellation reports that it made no change.

Accept a reviewed survivor

Record a decision not to require a test for a survivor:

rad remote accept \
  --run <run-id> \
  --finding <finding-id> \
  --reason equivalent \
  --note "Both forms have the same observable behavior"

--note is recommended but optional. The command accepts standard or custom reasons and rejects findings that are not survivors. Commit the resulting radforge-waivers.json file when the decision should apply to teammates, CI, and agents. See Accept a reviewed survivor for matching, auditing, and pruning behavior.

Retry a run

Retry a completed, failed, or canceled run with the same plan and source snapshot:

rad remote retry --run <run-id>

The server decides whether a run can be retried. A retry creates a new attempt but does not upload your current working tree. If the code or plan changed, generate and submit a new plan.

See Outputs and exit behavior for JSON fields, run states, and exit status.