Managing Runs

Favorite runs

Use teamcity run list --favorites to show the current user's favorite builds, including manually starred builds and builds TeamCity marked as important for you:

--favorites works with the existing run list filters and output modes.

Filtering

Use flags to narrow results:

Filtering by revision

Use --revision to find all builds that include a specific VCS commit:

Time-based filtering

Use --since and --until to filter by time. Accepts duration offsets (24h, 7d, 2w, 1mo, 4w2d5h) or ISO dates (2026-01-15, 2026-01-15T12:00:00Z):

Limiting results

Use --limit 0 to remove the result limit. When a finite --limit hides additional results, the CLI prints a hint on stderr (stdout and --json stay unchanged).

Without a job filter, searches start with a window of 5,000 recent builds. --limit 0 does not remove this search limit. If runs are missing, narrow the search with --project or --job, or increase the search window:

TEAMCITY_LOOKUP_LIMIT accepts a positive integer; zero and invalid values use 5,000.

Output options

run list flags

Specifying a branch and revision

For jobs with multiple VCS roots, repeat --revision ROOT=SHA[@BRANCH] to pin individual roots. Unspecified roots use TeamCity's normal revision selection. ROOT=@BRANCH uses the latest revision TeamCity has already fetched for that root; it does not fetch new commits. Use full refs for tags or pull requests.

Root IDs are the VCS root IDs shown by teamcity project vcs list, not numeric VCS root instance IDs. A root can appear only once, and bare and per-root forms cannot be mixed. Bare SHA/@head still applies to every root and resolves locally; per-root SHAs are passed verbatim. --branch is the build's logical branch; use @BRANCH to specify a pinned root's own branch independently. --dry-run displays the requested pins without resolving branch heads.

Build parameters

Pass custom parameters, system properties, and environment variables:

Build options

Versioned settings source

When a build configuration uses versioned settings, --settings chooses where the run's settings come from. Without the flag, the job's configured mode applies.

Tags and comments

Start and watch

Add --watch to follow the build after starting it:

You can also set a timeout or adjust the polling interval:

Personal builds

Include uncommitted local changes in a personal build:

By default, the CLI pushes your branch to the remote before starting a personal build. Use --no-push to skip this:

Dry run

Preview what would be triggered without actually starting a build:

run start flags

run tree flags

run watch flags

Listing artifacts

List artifacts from a run without downloading them:

Downloading artifacts

Downloads stay within the selected output directory, including when existing directories contain symlinks. Each file is staged before replacing its destination, so a failed or incomplete download preserves the previous file. A destination file symlink is replaced, not followed.

Download artifacts from a completed run:

The --timeout flag sets the maximum time for the entire download operation (default: 10m). Use longer values for large artifact sets, for example --timeout 1h.

Test history across builds

Pass --test NAME to follow a single test across builds instead of inspecting one run — the answer to "is this test flaky?". Scope it to a job, or leave --job off for a server-wide history:

The test name is shown once as a header and each build becomes a row; the trailing TESTS: summary doubles as a pass-rate. --failed/--muted narrow the history, and --json emits the raw occurrence array for your own flakiness analysis:

Diffing build logs

Pass --log to compare the two build logs as a colored unified diff. Timestamps, temp paths, and noisy git progress lines are normalized so the diff focuses on real content:

The output is piped through your pager ($PAGER, defaults to less). Strip colors and pipe to an external diff viewer for richer rendering:

Other forms

Open both runs in the browser:

Machine-readable output for scripts: