CLI Reference

Full reference for dstl8 graph build, push, repos, and status

dstl8 graph extracts a code graph snapshot from a repo and pushes it to Dstl8. Extraction always runs locally; build never uploads anything, and push uploads only the metadata artifact.

dstl8 graph build --dry-run          # audit: print every byte that would be sent
dstl8 graph build -o graph.json      # write the artifact for inspection
dstl8 graph push                     # extract + upload (run from the repo root)
dstl8 graph push ~/src/checkout      # ... or point at a repo
dstl8 graph repos                    # repos with pushed graphs
dstl8 graph status github.com/acme/checkout

push, repos, and status need credentials: a logged-in profile (dstl8 login), or DSTL8_API_TOKEN + DSTL8_API_URL in headless environments. build works fully offline.

dstl8 graph build [path]

Extracts the snapshot without uploading. path defaults to the current directory. Prints a human summary; the artifact itself goes wherever you point it:

• --dry-run — summary on stderr, the full artifact JSON on stdout (so it pipes cleanly into jq). Writes nothing.

• -o graph.json — write the artifact to a file.

• --json — summary on stderr, artifact JSON on stdout.

• none of the above — summary only, with a reminder that nothing was uploaded.

Flags (all of these are shared with push):

Flag	Description
--repo	Repo identity override (owner/name or full remote URL; default: detected from git)
--commit	Commit SHA override (full 40-char; default: git HEAD)
--branch	Branch name override (identity fallback for gitless environments)
--default-branch	Default branch override (default: origin/HEAD, falling back to the current branch)
--commit-time	Commit time override, epoch seconds (gitless environments; default: from git)
--service name=glob	Service mapping (repeatable; wins over service detection for that name)
--exclude glob	Exclude glob, gitignore syntax (repeatable; applied last — see evaluation order)
--no-diff	Skip diff computation against the previous snapshot
--include-tests	Index test sources too. They are excluded by default so a runtime pattern never resolves to a fixture — see test sources
--no-symbols	Skip the deep graph (symbols, import/dependency edges, external deps)
--json	Print the artifact (build) or push result (push) as JSON

build-only flags:

Flag	Description
-o, --output	Write the artifact JSON to a file
--dry-run	Print summary + full artifact JSON without writing anything

--service accepts repeated name=glob pairs; repeating a name merges its globs, and a bare name (no =) declares the service with no path scope:

dstl8 graph build --service checkout='cmd/checkout/**' \
                  --service checkout='payments/**' \
                  --service checkout-worker='cmd/worker/**'

dstl8 graph push [path]

Builds the snapshot (or loads one with --file) and uploads it. Before uploading, the server's latest snapshot is checked:

• Hash skip: if the server already has a hash-equal snapshot collected less than 30 days ago, the upload is skipped entirely. An older identical snapshot is re-pushed on purpose, so the server refreshes it back into the retention window.

• Diff baseline: the server's latest snapshot is the baseline for the per-push diff. If the previous snapshot can't be fetched (aged out, network), the push degrades to a files-only diff and proceeds with a warning.

• Branch gate: only the repo's default branch is tracked. A push from any other branch prints the server's message as a skip (Skipped: …) and exits 0 — a mis-wired PR trigger never fails a build.

After a new snapshot is stored, a ci platform event (reason=codegraph.pushed) is dropped on the events timeline, deduplicated by commit SHA. Suppress it with --no-event.

push-only flags (plus all shared flags above):

Flag	Description
--file graph.json	Upload a previously built artifact instead of extracting (validated before upload)
--no-event	Don't emit the codegraph.pushed platform event

Push output distinguishes the three server outcomes:

Pushed github.com/acme/checkout@9f2c1ab4e5d6 (main)         # new snapshot stored
Refreshed github.com/acme/checkout@9f2c1ab4e5d6 (unchanged graph, retention window renewed)
Server already has github.com/acme/checkout@9f2c1ab4e5d6 (unchanged graph)

With --json, the push result (created/refreshed flags, repo, commit, branch) prints as one JSON object for scripts.

dstl8 graph repos

Lists every repo in your org with a pushed code graph: branch, file and log-site counts, latest commit, and collection time. --json prints one JSON object per repo (NDJSON).

dstl8 graph status <repo>

Shows the latest snapshot for one repo — services (with how each was detected), latest commit, graph hash, counts, and extractor version. The repo key is the normalized remote, e.g. github.com/acme/checkout. --json for machine output.

Exit codes

Situation	Behavior
Clean run	Exit 0
Parse errors in individual files	Warnings, exit 0 — files stay in the inventory, counted in stats.parse_errors
Push from a non-default branch	Prints the server's Skipped: message, exit 0
Server already has the graph (hash skip)	Prints the skip reason, exit 0
Total failure — unresolvable repo identity, zero files, auth/network errors	Exit 1

Examples

Local audit before adopting

dstl8 graph build --dry-run | jq '.log_sites | length'
dstl8 graph build --dry-run | jq '.files[].path' | head

Write the artifact for security review, push the reviewed bytes

dstl8 graph build -o graph.json
# ... review graph.json ...
dstl8 graph push --file graph.json

Headless CI push

export DSTL8_API_TOKEN="dstl8_…"                 # from your secrets store
export DSTL8_API_URL="https://acme.app.dstl8.ai"
dstl8 graph push --json

No profile, no browser login, no ~/.config/dstl8 — the environment pair alone authenticates. Setting only one of the two is an error. See CI integration for full pipeline recipes.

Monorepo with explicit service globs

dstl8 graph push \
  --service checkout='services/checkout/**' \
  --service billing='services/billing/**' \
  --service shared-web='web/**'

A --service declaration wins over any detected mapping with the same name (it carries the same trust tier as an explicit .dstl8.yaml entry); detected services with other names are kept. Without the flag, services come from .dstl8.yaml, helm/k8s manifests, or docker-compose — see Configuration.

Gitless environment (exported tarball, no .git)

dstl8 graph push /srv/src/checkout \
  --repo acme/checkout \
  --commit 9f2c1ab4e5d6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 \
  --commit-time 1765731200 \
  --branch main --default-branch main

Normally all five values are detected from git; the flags exist for environments where git isn't available. Without git, the walk also can't use git ls-files, so .gitignore is not applied — rely on .dstl8ignore and --exclude there.

Leaner artifacts

dstl8 graph push --no-symbols      # log sites only: skip symbols, import edges, external deps
dstl8 graph push --no-diff         # skip the diff against the previous snapshot

--no-symbols still gives you pattern→source resolution and deploy diffs of log statements; it disables symbol search, code impact, and dependency answers for this repo. --no-diff disables per-deploy change sets — Dstl8 never diffs server-side.