Skip to main content

​
Command Overview

beacon ci runs Beacon telemetry collection for a single CI job without installing a persistent endpoint service or modifying user harness configuration.
Command syntax
beacon ci [command]
beacon ci exec starts a temporary local collector, injects supported agent telemetry configuration into one child command, writes normalized endpoint events to a CI runtime log, then validates that matching events were captured. For multi-step CI workflows or third-party GitHub Actions that launch agents internally, use beacon ci start and beacon ci finish.
beacon ci is designed for ephemeral CI jobs. For managed endpoint rollout on laptops or workstations, use beacon endpoint install.
For artifact upload, object storage export, and downstream SIEM handoff patterns, see CI Telemetry Exports.

​
Commands

beacon ci exec

Run a command with agent telemetry captured for the CI job.

beacon ci start

Start a detached telemetry session for later CI steps.

beacon ci finish

Stop, validate, and export a detached telemetry session.

beacon ci validate

Validate Beacon CI telemetry artifacts after a job step.

​
Artifact paths

By default, Beacon writes CI artifacts under $RUNNER_TEMP/beacon when RUNNER_TEMP is set. Otherwise it uses the system temp directory.
ArtifactDefault path
Runtime log$RUNNER_TEMP/beacon/runtime.jsonl
Collector config$RUNNER_TEMP/beacon/otelcol.yaml
Collector spool$RUNNER_TEMP/beacon/spool/otlp.jsonl
Use --log-path when your workflow needs a stable artifact path.

​
beacon ci exec

Run a child command with agent telemetry captured:
Run a child command with Claude Code telemetry captured
beacon ci exec -- claude -p "Review this repository"
beacon ci exec starts a temporary Beacon collector, runs the child command after --, stops the collector, validates the runtime log, and prints the artifact paths. The child command’s exit code is preserved. When GITHUB_ACTIONS=true, Beacon records GitHub Actions run metadata such as workflow, run ID, commit, ref, and actor in the CI session result. Other CI environments are marked as ephemeral CI runs when CI is set.

​
Flags

FlagDescription
--harness <harness>CI harness to configure. Defaults to claude; supported values include claude, codex, or comma-separated aliases
--log-path <path>CI runtime JSONL log path
--jsonPrint the execution and validation result as JSON
--min-events <count>Minimum matching events required during validation. Defaults to 1
--keep-artifactsKeep CI runtime log and collector config after exit. Enabled by default
--forward <destination>Optionally forward CI events to a customer-managed SIEM. Supported values are splunk and falcon
--forward-endpoint <url>SIEM HEC endpoint URL for the selected --forward provider. Tokens are read from BEACON_CI_SPLUNK_HEC_TOKEN or BEACON_CI_FALCON_HEC_TOKEN
--require-telemetry <bool>Fail when telemetry validation fails. Defaults to true; set false to warn without gating the child command result
--upload <destination>Upload the completed CI runtime JSONL after validation. Supported values are s3 and gcs; repeat for multiple destinations
Hidden operational flags are available for custom runners and tests, including --base-dir, --work-dir, --collector, --otlp-grpc-port, and --otlp-http-port. --upload s3 reads BEACON_CI_S3_BUCKET and optional BEACON_CI_S3_PREFIX. --upload gcs reads BEACON_CI_GCS_BUCKET and optional BEACON_CI_GCS_PREFIX.
--content-retention is deprecated and hidden. Beacon now captures supported CI content subject to redaction, sanitization, truncation, and event-size limits; the flag is accepted as a no-op for compatibility.

​
Examples

Capture Claude Code telemetry in GitHub Actions:
Capture Claude Code telemetry in GitHub Actions
beacon ci exec -- claude -p "Run the repository test suite and summarize failures"
Write CI telemetry to a known artifact path:
Write CI telemetry to a known artifact path
beacon ci exec \
  --log-path "$RUNNER_TEMP/beacon/runtime.jsonl" \
  -- claude -p "Review this pull request"
Run with telemetry validation as a warning instead of a hard gate:
Run with telemetry validation as a warning instead of a hard gate
beacon ci exec \
  --require-telemetry=false \
  -- claude -p "Inspect the changed files"
Print machine-readable output:
Print machine-readable output
beacon ci exec --json -- claude -p "Check release readiness"
Upload the completed CI runtime log to S3:
Upload the completed CI runtime log to S3
BEACON_CI_S3_BUCKET="my-beacon-telemetry" \
BEACON_CI_S3_PREFIX="github-actions" \
beacon ci exec --upload s3 -- claude -p "Review this pull request"

​
beacon ci start

Start a detached Beacon CI telemetry session for later workflow steps:
Start a detached Beacon CI telemetry session
beacon ci start --harness claude,codex
beacon ci start starts the local collector, writes a session state file, and prints/export telemetry environment variables. In the GitHub Action, these variables are written to $GITHUB_ENV so later run: or uses: steps can inherit them. Claude Code uses environment variables; Codex uses a generated CODEX_HOME with Beacon OTLP configuration.

​
Flags

FlagDescription
--harness <harnesses>Harnesses to configure. Defaults to claude,codex when omitted
--log-path <path>CI runtime JSONL log path
--state-path <path>CI session state path
--github-env <path>Optional GitHub Actions environment file to append exports to
--forward <destination>Optionally forward CI events to a customer-managed SIEM. Supported values are splunk and falcon
--forward-endpoint <url>SIEM HEC endpoint URL for the selected --forward provider

​
beacon ci finish

Stop and validate a detached Beacon CI telemetry session:
Stop and validate a detached session
beacon ci finish --min-events 1
beacon ci finish loads the state file from ci start, stops the collector, validates the runtime log, and optionally uploads the completed JSONL artifact.

​
Flags

FlagDescription
--state-path <path>CI session state path
--min-events <count>Minimum matching events required during validation. Defaults to 1
--require-telemetry <bool>Fail when telemetry validation fails. Defaults to true; set false to warn
--upload <destination>Upload the completed CI runtime JSONL after validation. Supported values are s3 and gcs; repeat for multiple destinations

​
GitHub Actions session example

- name: Start Beacon telemetry
  id: beacon
  uses: asymptote-labs/agent-beacon@v0.0.50
  with:
    mode: start
    harnesses: codex

- uses: openai/codex-action@main
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    codex-home: ${{ steps.beacon.outputs.codex-home }}
    prompt: "Review this pull request"

- name: Finish Beacon telemetry
  if: always()
  uses: asymptote-labs/agent-beacon@v0.0.50
  with:
    mode: finish
    min-events: "1"

​
beacon ci validate

Validate an existing Beacon CI runtime log:
Validate an existing Beacon CI runtime log
beacon ci validate
Validation checks that the runtime log exists, parses as Beacon JSONL, and contains at least the required number of matching harness events.

​
Flags

FlagDescription
--harness <harness>Required harness to validate. Defaults to claude
--log-path <path>CI runtime JSONL log path. Defaults to $RUNNER_TEMP/beacon/runtime.jsonl or the system temp path
--jsonPrint validation results as JSON
--min-events <count>Minimum matching events required. Defaults to 1

​
Examples

Validate the default CI artifact path:
Validate the default CI artifact path
beacon ci validate
Validate a custom runtime log:
Validate a custom runtime log
beacon ci validate --log-path "$RUNNER_TEMP/beacon/runtime.jsonl"
Require at least three Claude events:
Require at least three Claude events
beacon ci validate --min-events 3

CI Telemetry Exports

Export CI runtime JSONL through workflow artifacts, S3, GCS, or downstream pipelines.

Claude Code CI

Capture Claude Code telemetry in CI.

Codex CLI

Review Beacon support for Codex endpoint and CI telemetry.

Local testing

Validate Beacon runtime logs, events, dashboards, and MCP access locally.

Endpoint agent

Install persistent endpoint telemetry for managed devices.

Command reference

Browse Beacon commands by hierarchy.