Thanks for your interest in contributing to Bits CLI! This document covers the basics for getting a development environment running.
- Go 1.27.4 or later
- On macOS, the Xcode command line tools (
xcode-select --install) to build the ddviz helper
Clone the repository:
git clone git@github.com:datadog-labs/bits-cli.git
cd bits-cliBuild and test:
go build ./...
./scripts/test.shgo build ./... covers only the root module. ./scripts/test.sh runs the
unit tests of the root module and of the nested tools/licenses module,
which go test ./... from the repository root does not reach.
./scripts/build.sh builds bits and its libexec helpers
into an install prefix and prints it:
$ ./scripts/build.sh
/path/to/bits-cli/build/darwin-arm64
$ build/darwin-arm64/bin/bits --versionPass <os>/<arch> targets to build others, such as
./scripts/build.sh linux/amd64 linux/arm64. BUILD_LIBEXEC=0 skips the helpers.
go build builds bits alone; point it at built helpers with
BITS_LIBEXEC_DIR=build/darwin-arm64/libexec/bits.
Lint with the pinned golangci-lint configuration:
./scripts/lint.sh./scripts/lint.sh lints both modules, checks the shell scripts with
shellcheck when it is installed (CI always does), and verifies that
LICENSE-3rdparty.csv matches the dependency tree.
Run bits login to sign in through your browser. For API-key authentication,
set both DD_API_KEY and DD_APP_KEY, then select the mode and API site explicitly:
bits --auth api-key --site https://api.datadoghq.comThis uses the keys for the current invocation without changing your saved OAuth
session. Plain bits uses OAuth even when those environment variables are set.
Running Bits instances share token refreshes for the same OAuth login. Running
bits login again replaces that login, even when you choose the same account
and org. Restart existing instances to use the replacement; they stop using
credentials at their next check rather than switch a running conversation to a
new login. Requests already in flight may finish or fail with their original
credentials.
Older saved logins remain usable, but cannot distinguish another process's
refresh from a replacement login. An external credential change requires a
restart until you run bits login with a current version. If an older binary
refreshes a new login and drops its login identifier, current instances also
require a restart.
For an Assistant endpoint that acknowledges a request policy in a streaming
response header, set BITS_REQUIRED_RESPONSE_HEADER=Name=value. Bits checks
the exact header value before delivering streamed output and rejects redirects
for these requests, including multi-agent starts and conversation continuations. Leave it unset when no acknowledgment is required.
Configure the staging login origin and callback domain before signing in:
export BITS_STAGING_SITE=https://login.staging.test
export BITS_STAGING_DOMAIN=staging.test
export BITS_STAGING_CLIENT_ID=staging-test-client
bits login --site "$BITS_STAGING_SITE"Use your environment's actual values. BITS_STAGING_SITE and
BITS_STAGING_DOMAIN are required; BITS_STAGING_CLIENT_ID supplies an optional
default that bits login --client-id can override. The login origin must use
HTTPS and belong to the callback domain. API and token requests go to
api.<domain>.
Keep the staging configuration set while using the saved session. If it is
missing or names a different domain, Bits reports an error. To switch back to
production, run bits logout with the staging configuration still set, unset
the staging variables, and sign in again.
To omit selected variables from local shell commands run by Bits, set
BITS_EXEC_EXCLUDE_ENV to a comma-separated list of exact environment variable
names, such as PRIVATE_TOKEN,SESSION_KEY. Bits also omits this setting from
those commands. When unset, shell commands inherit the normal environment.
Tests that contact Datadog are opt-in:
BITS_OAUTH_E2E=1reuses your stored OAuth login.BITS_VIZ_E2E=1renders CPU charts through Datadog MCP and ddviz, and through the Datadog snapshot API. The ddviz test requires macOS 13+ and a built helper; both tests require a stored Bits login with the corresponding access.BITS_ASSISTANT_E2E=1requiresDD_API_KEY,DD_APP_KEY, and an explicitBITS_E2E_SITEnaming the Datadog API site.
For noninteractive runs, see the ADEEP delivery documentation.
BITS_VIZ=auto is the default. It uses ddviz for interactive previews when the
macOS helper is available, and Datadog snapshots otherwise. Snapshot previews
require a Datadog site and login that support the snapshot API. Set
BITS_VIZ=snapshot to use snapshots on any system, or BITS_VIZ=off to show
web sandbox links only. Terminal image support is required for inline previews;
without it, snapshot-only widgets appear as links. When a widget has no usable
fixed or live time range, snapshots and links default to the last hour.
BITS_GRAPHICS=auto (the default) detects inline images, including the startup logo.
Use BITS_GRAPHICS=on bits to bypass terminal identity checks, or
BITS_GRAPHICS=off bits to disable images and probes. Graphics still require
truecolor and a successful protocol probe; tmux, screen, and Zellij remain
disabled. Values are case-sensitive; unset, empty, or invalid values use auto.
The setting is read at startup and is not persisted.
- Create a branch for your change.
- Make your change, keeping commits focused.
- Make sure
./scripts/test.shand./scripts/lint.sh— the same scripts CI runs — both pass. - Open a pull request against
mainwith a clear description of the change and how it was tested. GitHub Actions runs lint, tests, and builds for every pull request.
.github/workflows/ci.yml runs on pull requests (forks included), pushes to
main, and queued merges. It is unprivileged (read-only token, no secrets,
SHA-pinned actions):
lint
build linux (ubuntu) ─┐ build.sh <os>/amd64 <os>/arm64, then test.sh
build darwin (macOS) ─┼─→ package (ubuntu): package.sh --sbom → dist artifact
build windows (Windows) ─┘
Each build job tests natively with BITS_LIBEXEC_DIR set to the helpers it
built for its host, then uploads its install prefixes. Release runs the same
workflow for its tag and publishes the dist artifact.
Releases are described in RELEASE.md.
LICENSE-3rdparty.csv is generated output: never hand-edit it. It covers every
external Go module whose source is part of the build/test closure of the
shipped root module (its go.sum entries with a zip hash), with the SPDX
license identifier and copyright holder of each module.
- After any dependency change, run
./scripts/generate-licenses.shand commit the regenerated CSV. This includes the weekly Dependabot pull requests. - The drift check runs as part of
./scripts/lint.shand compares the committed CSV byte for byte with the freshly generated one. - If a module cannot be resolved (unknown license, no copyright statement, or
an underivable upstream origin), the generator fails listing the module.
Fix it with an entry in
tools/licenses/overrides.json, which requires a one-linereasonfor each entry. Stale override keys and license overrides contradicting a confident detection fail the run, so corrections always stay deliberate. - The generator also refuses any copyleft dependency (GPL, AGPL, LGPL, EPL).
If one is ever deliberate, acknowledge it with
"copyleft": trueand a reason in the same overrides file. - The generator's own dependencies (including the license detector) are
excluded from the inventory by design:
tools/licensesis a nested module, so its dependency tree never enters the root module'sgo.sum.
By contributing to Bits CLI, you agree that your contributions will be licensed under the Apache-2.0 License.
Experimental subagents are enabled automatically for numeric organization ID 2.
Bits checks the authenticated organization at startup with a three-second
timeout unless BITS_USE_EXPERIMENTAL_SUBAGENTS is 1 or 0. If the lookup
fails, it keeps the regular endpoint. The lookup uses
/api/v1/legacy_current_user, which requires first-party access for OAuth;
credentials without access to this endpoint must use the environment opt-in
below.
For other organizations, the regular Assistant endpoint remains the default.
Opt into experimental subagents with BITS_USE_EXPERIMENTAL_SUBAGENTS=1 bits, or with
BITS_USE_EXPERIMENTAL_SUBAGENTS=1 bits run --prompt '…' --delivery adeep.
BITS_USE_EXPERIMENTAL_SUBAGENTS=0 keeps the regular endpoint, even for
organization 2. Unset, empty, or other values fall back to the organization check.
The setting is not persisted.
When subagents are enabled, eligible turns use multi-agent run
endpoints with the cli profile. The server must support these endpoints and enable
command-assistant-multi-agent-runs for the organization. Each turn creates a new
run while keeping the conversation ID; history and conversation management use
the existing APIs. Child answers stay out of the final root answer, and local
tools from different agents can run concurrently, subject to the same permission
checks and a limit of 16 executions.
Turns using --reasoning, explicit raw history, or payloads exceeding the bounded
run API's limits use the regular Assistant endpoint, including its tool-result
continuations. This preserves existing image and instruction capabilities. Tests verify that
the shipped tool definitions fit the run API limits. There is no retry through
another endpoint after a run has started.
For a test drive, set BITS_CUSTOM_HEADERS='test-drive-NAME=1'. The shared
request builder forwards these headers on start, conversation continuation,
tool-result submission, cancellation, and regular API requests.