Metadata-Version: 2.5
Name: stacktrace-cli
Version: 0.4.1
Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
Project-URL: Homepage, https://stacktrace.ai
Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
License-Expression: LicenseRef-Proprietary
Keywords: agent-security,ai-security,openaca,stacktrace
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx<1.0.dev0,>=0.28.1
Requires-Dist: openaca==0.7.0
Requires-Dist: openaidr==0.3.0
Requires-Dist: posthog<8,>=7.0
Description-Content-Type: text/markdown

# stacktrace-cli

Detection and response for AI coding agents, from the command line.

Coding agents read files, run shell commands and call MCP servers on their own
initiative, and they write a transcript of every bit of it to disk.
`stacktrace` reads those transcripts, correlates what ran against the
components the agent is built from, and reports the security and reliability
findings in it — locally, on the machine the agent worked on.

The PyPI distribution is `stacktrace-cli`; the command it installs is
`stacktrace`. The two names differ because the bare `stacktrace` name on PyPI
belongs to an unrelated project.

## Installation

```bash
uv tool install stacktrace-cli     # isolated; recommended
# or
pip install stacktrace-cli
```

Requires Python 3.11 or newer.

```console
$ stacktrace --version
stacktrace 0.4.1 (openaca 0.7.0)
```

## Quick start

```bash
stacktrace sessions      # what the agents on this machine did
stacktrace detect        # what is wrong with it
stacktrace monitor       # the same, live in a browser
```

## Commands

| Command | |
|---|---|
| `sessions` | Print what the agents on this machine actually did. |
| `detect` | Find security and reliability findings in what agents did. |
| `monitor` | Watch this machine's agents in a browser, live. |
| `remote` | Configure remote endpoint services and upload to Stacktrace Cloud. |
| `scan` | Scan a repository or endpoint for agent-composition findings. |
| `bom` | Generate an Agent BOM for a repository or endpoint. |
| `policy` | Validate and compile restrictive endpoint policies. |

The last three are composition analysis, supplied by
[`openaca`](https://pypi.org/project/openaca/) and available under either
name.

## What it looks like

```console
$ stacktrace sessions --since 2d --include-content
claude-code:s1  [claude-code]  2026-08-27T09:00:00+00:00  2 turns  2 calls
  2026-08-29T12:00:00+00:00  assistant: Reading the changelog before drafting the release notes.
    ok                28c  Read
        result: ## 0.4.0 - correlate, detect
  2026-08-29T12:00:00+00:00  assistant: Filing the release-notes follow-up.
                        -  github/create_issue

Summary — 1 sessions, 2 turns, 2 tool calls

  agent kinds
          1  claude-code

  tools called (2 distinct)
          1  Read
          1  github/create_issue

  MCP servers reached (1 distinct)
          1  github

  0 subagent turns · 0 results abridged upstream · 1 ok

1 of 2 calls returned with no outcome the collector could establish; the agent's parser supplies no success signal.
```

A blank status column is the collector's `unknown`, not a pending call: the
client recorded no outcome that could be established, and the closing line
counts those rather than filling one in.

## What `detect` finds

Three kinds of finding, under two families that carry separate severity
ladders — a blocked agent and a leaked credential do not belong on one scale.

**Security** — a credential reaching an outbound call; success reported against
the session's own evidence of failure.

**Reliability** — why the agent stopped, in words, with what to do about it: a
spend limit reached, a safety check blocking, a service refusing a call.

Findings are correlated against an Agent BOM before they are reported, so one
that names a component names the one a call actually reached.

## What leaves your machine

**On a default run**, `detect` reads the record on this machine. It needs no
model, no credential and no account, and nothing derived from a session — no
prompt, no tool argument, no result — is sent anywhere.

One network call is made even then, and it is worth stating because *nothing
leaves* is not what happens: correlation matches advisories by sending the
package coordinates of the components a session invoked to osv.dev.
Coordinates only.

**One flag pair changes that, and it has to be typed in full.** `detect
--reasoning --analyzer jev` adds a third stage that sends two small states to
TypeSafe's Jev: a *gate* carrying the closing lines of each hand-back, capped,
which ends most sessions there — and, for a session that clears it, one
per-call *window* each carrying a completion claim, one verification command
and the tail of its output. Neither flag has a default and neither implies the other,
so naming the vendor is your act rather than ours (ADR-0033). Without both,
stage three is not asked. `detect --analyzer jev` alone reads back what such a
run already paid for and commissions nothing (ADR-0035).

`sessions` omits prompts, tool arguments and results unless you pass
`--include-content`. `monitor` binds to loopback only, and refuses a
non-loopback address rather than warning about it.

**Usage telemetry is enabled by default.** Disable it before normal use with
`stacktrace telemetry off`. An existing opt-out stays off; unreadable or invalid
settings also disable telemetry. The first enabled usage event creates a random
identifier. The daemon sends four event types to PostHog's US region: an enabled
identity first becomes active, a session starts, a finding is delivered, or a
product error occurs. Event fields describe the rule, severity, destination,
reason code or error category, the session id and agent kind for session and finding events, plus CLI version, OS, environment, whether it ran in a Claude Code cloud session (`remote`) and timestamp.
`environment` is `production` unless `STACKTRACE_TELEMETRY_ENV` is set to
`staging`, `development` or `test`. They do not
include prompts, tool arguments, results, full findings, paths or repository
names. The persistent identifier and timing mean this is not anonymous data.

`stacktrace telemetry show` prints the state, the destination, the environment,
the identifier and every event with every property it may carry. `off` deletes
the local identifier; it does not delete previously uploaded records, and an
event already handed to the client may still be sent. `stacktrace telemetry on`
enables telemetry again under a new identity (ADR-0039).
`STACKTRACE_TELEMETRY_DISABLED=1` sends nothing, for CI and test runs.

## Status

Beta, and under active development.

`sessions`, `detect` and `monitor` work end to end today. Session collection
currently reads Claude Code transcripts; further agent kinds are in progress
upstream in [OpenAIDR](https://github.com/open-agent-security/openaidr).

## Built on

Two Apache-2.0 packages, neither of which depends on this one:
[`openaca`](https://pypi.org/project/openaca/) for agent composition analysis,
and [`openaidr`](https://pypi.org/project/openaidr/) for session collection.

## Licence

Proprietary. © Stacktrace AI, Inc. — [stacktrace.ai](https://stacktrace.ai)
