Quickstart

Prepare a repository and start its first mutation run through the CLI or GitHub App.

Onboard with a coding agent

Open your repository in a coding agent and paste this prompt:

Read https://docs.radforge.dev/quickstart.md, inspect this repository, and guide me through Radforge setup using its version-pinned installer. Start with a dry run. Ask before installing software, writing files, using credentials, or uploading source.

The agent should inspect the repository first. If rad is missing, it should explain that installation uses the authenticated GitHub CLI to access the private release, then ask for approval to use those credentials and install software. After approval, check access with gh auth status and run:

installer="$(mktemp)"
gh api \
  --method GET \
  -H "Accept: application/vnd.github.raw" \
  "repos/Radforge-Dev/radforge/contents/plugins/radforge/scripts/install-radforge.sh?ref=v0.1.0-rc.2" \
  > "$installer"
bash "$installer" --version v0.1.0-rc.2

The version-pinned installer detects the operating system and architecture, downloads the matching archive and checksum, verifies the checksum, installs rad under ~/.local/bin, and prints the installed version. Do not ask the user to download or place the archive when gh auth status succeeds. If access fails, stop and ask the user to authenticate GitHub or obtain private-beta access. If ~/.local/bin is not on PATH, use "$HOME/.local/bin/rad" for the remaining commands.

Before you begin

• Install the rad CLI.
• Obtain private-beta access and a repository-scoped API token from Radforge onboarding.
• Use a cloned Git repository with one of the supported setups listed on the installation page.

Prepare the repository

1. From the repository root, preview the setup changes:

rad init --dry-run

The command prints the detected profiles and setup plan without writing files. If it finds multiple profiles, choose the roots to initialize. Profiles can use different languages or share a language.

2. Review the profile selection, .gitignore, and coding-agent skill changes, then apply them interactively:

rad init

For unattended setup, repeat --profile-root for each selected root. For example:

rad init --yes \
  --profile-root services/api \
  --profile-root apps/web

3. Check the repository:

rad doctor

The first line reports Radforge doctor: ready when local setup is complete. If it reports needs_setup, fix each failed check before continuing.

Authenticate the CLI

1. Load RADFORGE_API_TOKEN from your password manager, operating-system keychain, or CI secret store. Do not type the token into a shell command or save it in shell history.
2. Set the production API origin and confirm that the token is present without printing it:

export RADFORGE_REMOTE_URL="https://api.radforge.dev"
test -n "${RADFORGE_API_TOKEN:-}" && printf 'RADFORGE_API_TOKEN is set\n'

3. Verify hosted access:

rad remote doctor

The command reports Radforge remote doctor: ready, the repository, and the hosted profiles available to the token. See Hosted authentication if it does not.

Verify hosted execution with a bounded canary

Preview a three-mutant canary without uploading source:

rad verify --language typescript --dry-run --json

For Go or Python, replace the language with go or python. In a mixed repository, verify one profile at a time and use --profile-root, for example --profile-root apps/web. The preview shows the deterministically selected source and tests. Remote verification captures the complete Git-tracked repository snapshot even though mutation and test execution are bounded. When incremental transfer is available, it uploads only file content that has not already been proved for this repository.

After reviewing the preview, approve and wait for the hosted canary:

rad verify --language typescript --yes --json

Surviving mutants do not fail setup verification. Either successful terminal state proves that source upload, dependency setup, native tests, mutation execution, and result publication worked.

Run a Go, TypeScript, JavaScript, or Python change

1. Fetch the current remote refs. If the default branch is not main, replace origin/main in the next command:

git fetch origin

2. Plan the changes and submit them:

rad changed --since-ref origin/main --json

The command prints a JSON run record. A new run starts in pending_dispatch with one pending attempt:

{
  "created": true,
  "run": {
    "id": "run-1",
    "state": "pending_dispatch",
    "authoritativeAttemptId": "",
    "attempts": [
      {
        "id": "attempt-1",
        "state": "pending",
        "findingsCount": 0
      }
    ]
  }
}

3. Replace <run-id> with the returned run ID and check it until it reaches a terminal state:

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

succeeded_with_findings means Radforge reported one or more survivors or coverage gaps. succeeded_without_findings means the run completed without findings. Other terminal states identify cancellation, unsupported input, a timeout, or a customer or infrastructure failure.

For Python, the repository must use pytest with pyproject.toml and uv.lock. The same Python-only change can also run through the GitHub App. If a scope or pull request changes more than one of Go, Python, and TypeScript/JavaScript, split it into separate runs or pull requests because one run cannot span language profiles.

Optional: Review a plan before submission

For any supported language, write the plan to a file, inspect it, then submit it:

rad changed --since-ref origin/main --dry-run --json > plan.json
rad remote run --artifact plan.json

Optional: Limit the run

If the plan contains too many mutations, set --budget, add one or more --exclude patterns, or use a scope file that lists exact source paths. Use --allow-broad-tests only when you accept running a broad test set because Radforge could not select a smaller one.