Docs
Set up land, use it in CI, read a verdict, check a commit, and know its limits.
Set up
Works with Claude Code, Codex and any agent that can run a command, in any language whose tests run on Linux. You name the test commands, and land skips the ones a change can't affect.
Install the land CLI and sign in
On the machine your agents run on. It signs you in with GitHub and installs the land skill for Claude Code and Codex.
curl -fsSL https://useland.dev/install | sh land login
The installer puts
landin~/.local/bin. If your shell saysland: command not found, addexport PATH="$HOME/.local/bin:$PATH"to your shell profile.Pick a plan and start your free day
Your first day is free, with no card. To keep landing after that, open your dashboard (
land statusprints its link) and choose pay as you go or monthly.Add the repository, once
In the repository.
--dry-runshows what would upload: committed files only, no history, never.env. land finds the tests, builds the environment from your dependency files, and records which tests already fail.land add --dry-run land add
To run several test commands as separate, named checks, repeat
--test NAME=CMD. Commit a.land/setup.shat the repo root first that installs everything the tests need (toolchain, pinned package manager, dependencies): land runs it once on a plain Debian machine with the network on, and whatever it leaves is the environment. The tests then run offline with exactly your command.--checker inspect(repository owner) makes each named check rerun only when something it read changed.Languages: Python, Go, Ruby (RSpec with a committed Gemfile.lock), and TypeScript/JavaScript (vitest, node --test or mocha) run only the tests a change can affect. Jest, Rust, other Ruby, Java and Kotlin (Maven or Gradle), PHP, C#, and C or C++ (CMake or make) run the whole suite on every change for now. Pass
--test '<command>'if land picks the wrong one.Tell your agents where finished work goes
Add these lines to the repository's
CLAUDE.md(AGENTS.mdfor Codex and others). The installer also gives your agents the land skill, which covers the same steps.When work is done, run `git fetch origin main`, then `land merge <branch>... --onto main`. land merges the branches with main and runs the tests it could affect. It prints JSON: `landed`, and `refused` with the failing tests. Fix a refusal and run it again. Then run the `local.push` command it prints. It sends the result together with land's signature: `git push --atomic origin <commit>:refs/heads/main refs/land/attestations`. With several agents, each works in its own worktree and branch, and one agent runs `land merge` with every branch. Never edit, skip or delete a test to get work through.
land never writes to GitHub and never holds your GitHub access: your agent sends the result with its own. If GitHub blocks direct pushes to main, either allow the account your agents use, or have them send the commit and
refs/land/attestationsto a branch and open a pull request with it.
CI and cloud agents
Where there's no browser to sign in, make a token on your dashboard for the repositories it may use and set it as LAND_TOKEN. land merge then works in a fresh checkout with no login. A token can't add repositories or change a test command, and you can revoke it any time.
LAND_TOKEN=$LAND_TOKEN land merge "$BRANCH" --onto main
Reading a verdict
$ land merge sub/api sub/ledger --onto main { "landed": ["sub/api"], "refused": [{ "who": "sub/ledger", "why": "tests_failed", "failing": [{ "test": "tests/test_ledger.py::test_reverse", "assert": "assert 110 == 90" }], "repro": { "commit": "071366837c", "run": "python -m pytest tests/test_ledger.py::test_reverse" }, "hitBy": "sub/api" }], "guarding": "3/3", "removed_tests": [], "newly_skipped": [], "tests_changed": [], "local": { "push": "git push --atomic origin 8364fb3…:refs/heads/main refs/land/attestations" } }
| why | what your agent does |
|---|---|
| tests_failed | Fix the code those tests use (hitBy names the other branch it clashes with), run land merge again |
| conflict | Rewrite your version of the named entity on top of the one that landed, run land merge again |
| collection | Tests could not load (an import or syntax error). Fix it, run land merge again |
| dependencies | The new dependencies would not install. Fix the dependency files, or add the tool to .land/setup.sh, run land merge again |
| policy | The change edits protected tests. Revert those edits |
| env, timeout, oom | The run failed, not your code. Run land merge again |
| no_plan | Nothing was checked. Pick a plan on your dashboard, then run land merge again |
| "dirty" | Commit the subagent's work in that worktree, merge again |
| "state": "running" | Run the same land merge again to wait for the result |
| exit code 4 | land could not check this run (its side, not your change). Run land merge again |
Checking a commit
Anyone can check, offline, that a commit on main was proven. Save land's public keys once, fetch the signatures that came with the result, and verify.
curl -fsS https://api.useland.dev/v1/land/keys -o land-keys.json git fetch origin refs/land/attestations:refs/land/attestations land verify HEAD --pubkey land-keys.json --protected main
It exits 0 when the commit's exact files passed, and 1 with the reason when they did not.
The keys come from land's API, described in openapi.json. The API is versioned in its address (/v1). A breaking change gets a new version, and the old one keeps working for at least 90 days after its removal is announced on this page.
Limits
- Skipping works per test command. A suite that runs as one command reruns whole whenever a file it reads changes, so split it into smaller commands.
- On very small suites, land's fixed cost per check (about a second) can be more than just running every test.
- A change to a dependency file, test configuration or data file reruns every test that reads it, and land reinstalls dependencies first.
- Tests run on Linux, offline, each check in a small virtual machine of its own. Tests that need the network, macOS or Windows don't work yet.
- A flaky check still refuses the change. land reruns a failing command once on the same code, and if it passes the second time the verdict names it flaky. land never lands a change on a retry, and there is no quarantine.
- land checks that tests pass. It can't catch a bug no test covers.
Pricing
Most CI is billed by the machine minute, so a slower pipeline costs more and every rerun after a rebase is another charge. land charges only for changes that reach main. It earns nothing from running tests your change can't affect, and changes it refuses are free.
Your first day is free, with no card, and both plans also start with a 1-day free trial after checkout. You can cancel any time from your dashboard. See the plans.