Skip to content

Latest commit

 

History

History
231 lines (179 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

231 lines (179 loc) · 10.1 KB

Contributing to Bits CLI

Thanks for your interest in contributing to Bits CLI! This document covers the basics for getting a development environment running.

Prerequisites

  • Go 1.27.4 or later
  • On macOS, the Xcode command line tools (xcode-select --install) to build the ddviz helper

Getting started

Clone the repository:

git clone git@github.com:datadog-labs/bits-cli.git
cd bits-cli

Build and test:

go build ./...
./scripts/test.sh

go 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 --version

Pass <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.

Authentication for development

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.com

This 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.

Staging

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.

Integration tests

Tests that contact Datadog are opt-in:

  • BITS_OAUTH_E2E=1 reuses your stored OAuth login.
  • BITS_VIZ_E2E=1 renders 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=1 requires DD_API_KEY, DD_APP_KEY, and an explicit BITS_E2E_SITE naming the Datadog API site.

For noninteractive runs, see the ADEEP delivery documentation.

Widget previews

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.

Development workflow

  1. Create a branch for your change.
  2. Make your change, keeping commits focused.
  3. Make sure ./scripts/test.sh and ./scripts/lint.sh — the same scripts CI runs — both pass.
  4. Open a pull request against main with a clear description of the change and how it was tested. GitHub Actions runs lint, tests, and builds for every pull request.

Continuous integration

.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.

Third-party licenses

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.sh and commit the regenerated CSV. This includes the weekly Dependabot pull requests.
  • The drift check runs as part of ./scripts/lint.sh and 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-line reason for 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": true and a reason in the same overrides file.
  • The generator's own dependencies (including the license detector) are excluded from the inventory by design: tools/licenses is a nested module, so its dependency tree never enters the root module's go.sum.

License

By contributing to Bits CLI, you agree that your contributions will be licensed under the Apache-2.0 License.

Multi-agent Assistant transport

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.