Runs represent build executions in TeamCity. The teamcity run command group lets you start builds, monitor them in real time, view logs and test results, manage artifacts, and organize runs with tags, comments, and pins.
Listing runs
View recent builds with teamcity run list:
teamcity run list
Filtering
Use flags to narrow results:
# Builds for a specific job
teamcity run list --job MyProject_Build
# Filter by project
teamcity run list --project MyProject
# Filter by branch
teamcity run list --branch main
# Filter by status
teamcity run list --status failure
# Filter by user who triggered the build
teamcity run list --user alice
teamcity run list --user @me
# Combine filters
teamcity run list --job MyProject_Build --status failure --branch main
Time-based filtering
Use --since and --until to filter by time:
# Builds from the last 24 hours
teamcity run list --since 24h
# Builds from a specific date onward
teamcity run list --since 2026-01-15
# Builds in a time range
teamcity run list --since 2026-01-15 --until 2026-01-20
Limiting results
teamcity run list --limit 20
Output options
# JSON output (see Scripting and automation for details)
teamcity run list --json
teamcity run list --json=id,status,webUrl
# Plain text for scripting
teamcity run list --plain
teamcity run list --plain --no-header
run list flags
Flag
Description
-j, --job
Filter by job (build configuration) ID
-p, --project
Filter by project ID
-b, --branch
Filter by branch name
--status
Filter by status: success, failure, running, error, or unknown
-u, --user
Filter by the user who triggered the build. Use @me for the current user.
--since
Show builds finished after this time (for example, 24h, 2026-01-21)
--until
Show builds finished before this time
-n, --limit
Maximum number of runs to display
--json
Output as JSON. Use --json= to list available fields, --json=f1,f2 for specific fields.
--plain
Tab-separated output for scripting
--no-header
Omit header row (use with --plain)
-w, --web
Open the list in the browser
Starting a run
Trigger a new build with teamcity run start:
teamcity run start MyProject_Build
Specifying a branch and revision
# Build a specific branch
teamcity run start MyProject_Build --branch feature/login
# Pin to a specific Git commit
teamcity run start MyProject_Build --branch main --revision abc123def
Build parameters
Pass custom parameters, system properties, and environment variables:
# Clean all source files before building
teamcity run start MyProject_Build --clean
# Rebuild all dependencies
teamcity run start MyProject_Build --rebuild-deps
# Rebuild only failed dependencies
teamcity run start MyProject_Build --rebuild-failed-deps
# Add to the top of the queue
teamcity run start MyProject_Build --top
# Run on a specific agent
teamcity run start MyProject_Build --agent 5
Add --watch to follow the build after starting it:
teamcity run start MyProject_Build --branch main --watch
Personal builds
Include uncommitted local changes in a personal build:
# Auto-detect changes from Git working directory
teamcity run start MyProject_Build --local-changes
# From a patch file
teamcity run start MyProject_Build --local-changes changes.patch
# From stdin
git diff | teamcity run start MyProject_Build --local-changes -
By default, the CLI pushes your branch to the remote before starting a personal build. Use --no-push to skip this:
teamcity run start MyProject_Build --local-changes --no-push
Dry run
Preview what would be triggered without actually starting a build:
teamcity run start MyProject_Build --dry-run
run start flags
Flag
Description
-b, --branch
Branch to build
--revision
Pin build to a specific Git commit SHA
-P, --param
Build parameters as key=value (can be repeated)
-S, --system
System properties as key=value (can be repeated)
-E, --env
Environment variables as key=value (can be repeated)
-m, --comment
Build comment
-t, --tag
Build tag (can be repeated)
--personal
Run as a personal build
-l, --local-changes
Include local changes. Accepts git (default), - (stdin), or a file path.
--no-push
Skip auto-push of branch to remote
--clean
Clean source files before building
--rebuild-deps
Rebuild all dependencies
--rebuild-failed-deps
Rebuild failed or incomplete dependencies only
--top
Add to the top of the build queue
--agent
Run on a specific agent (by ID)
--watch
Watch the build after starting it
-n, --dry-run
Preview without starting
--json
Output as JSON
-w, --web
Open run in browser
Viewing run details
teamcity run view 12345
teamcity run view 12345 --web
teamcity run view 12345 --json
Watching a run
Monitor a running build with live updates:
teamcity run watch 12345
Stream build logs while watching:
teamcity run watch 12345 --logs
Set a custom refresh interval or timeout:
teamcity run watch 12345 --interval 10
teamcity run watch 12345 --timeout 30m
Use --quiet for minimal output that shows only state changes and the final result:
teamcity run watch 12345 --quiet
run watch flags
Flag
Description
-i, --interval
Refresh interval in seconds
--logs
Stream build logs while watching
-Q, --quiet
Minimal output — only state changes and result
--timeout
Stop watching after this duration (for example, 30m, 1h)
Viewing build logs
View the log output from a run:
teamcity run log 12345
View the log for the latest run of a specific job:
teamcity run log --job MyProject_Build
Show failure diagnostics — build problems, failed tests with full stack traces, and whether each failure is new or pre-existing:
teamcity run log 12345 --failed
Bypass the pager and output raw text:
teamcity run log 12345 --raw
Canceling a run
Cancel a running or queued build:
teamcity run cancel 12345
teamcity run cancel 12345 --comment "Canceling for hotfix"
Use --force to skip the confirmation prompt:
teamcity run cancel 12345 --force
Restarting a run
Restart a run with the same configuration:
teamcity run restart 12345
teamcity run restart 12345 --watch
teamcity run restart 12345 --web
Artifacts
Listing artifacts
List artifacts from a run without downloading them:
teamcity run artifacts 12345
teamcity run artifacts --job MyProject_Build
teamcity run artifacts 12345 --path html_reports/coverage
teamcity run artifacts 12345 --json
Downloading artifacts
Download artifacts from a completed run:
teamcity run download 12345
teamcity run download 12345 --dir ./artifacts
teamcity run download 12345 --artifact "*.jar"
Test results
Show test results from a run:
teamcity run tests 12345
teamcity run tests --job MyProject_Build
Show only failed tests:
teamcity run tests 12345 --failed
Limit the number of results:
teamcity run tests 12345 --limit 50
teamcity run tests 12345 --json
VCS changes
Show the VCS commits included in a run:
teamcity run changes 12345
Show commits only (without file listings):
teamcity run changes 12345 --no-files
teamcity run changes 12345 --json
Pinning runs
Pin a run to prevent it from being cleaned up by retention policies:
teamcity run pin 12345
teamcity run pin 12345 --comment "Release candidate"
Remove the pin:
teamcity run unpin 12345
Tagging runs
Add tags to a run for categorization and filtering:
teamcity run tag 12345 release
teamcity run tag 12345 release v2.0 production
Remove tags:
teamcity run untag 12345 release
teamcity run untag 12345 release v2.0
Comments
Set a comment on a run:
teamcity run comment 12345 "Deployed to production"
