The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
cli work
narrow-adventuree6dd6ecd043b
diff --git a/cli/README.md b/cli/README.mdindex e8b5be5a..70ca58e2 100644--- a/cli/README.md+++ b/cli/README.md@@ -4,7 +4,13 @@ A Go CLI for the [Traceway](https://github.com/tracewayapp/traceway) observabili## Install-Prebuilt binaries are published with every release at+One-line install for macOS and Linux (runs [`install.sh`](install.sh): detects OS/arch, downloads the latest release, verifies its sha256, installs to `/usr/local/bin` or `~/.local/bin` — no sudo; `TRACEWAY_CLI_VERSION` pins a version, `TRACEWAY_INSTALL_DIR` overrides the target):++```bash+curl -fsSL https://cli.tracewayapp.com/install.sh | sh+```++Or install manually: prebuilt binaries are published with every release at[github.com/tracewayapp/traceway/releases](https://github.com/tracewayapp/traceway/releases)under the matching `CLI vX.Y.Z` tag — the CLI version tracks the backend release.Download the archive for your platform (`traceway_<version>_<os>_<arch>.tar.gz`,diff --git a/cli/install.sh b/cli/install.shnew file mode 100644index 00000000..59fda741--- /dev/null+++ b/cli/install.sh@@ -0,0 +1,114 @@+#!/bin/sh+# Traceway CLI installer (Linux / macOS).+#+# curl -fsSL https://cli.tracewayapp.com/install.sh | sh+#+# Served from cli.tracewayapp.com (Cloudflare, uploaded manually); this file+# is the source of truth — re-upload it after changing it. New CLI releases+# need no re-upload: the script resolves the latest release at runtime.+# For Windows, download the .zip from https://github.com/tracewayapp/traceway/releases.+#+# Optional:+# TRACEWAY_CLI_VERSION Version to install, e.g. 1.9.3 (default: latest CLI release)+# TRACEWAY_INSTALL_DIR Target directory (default: /usr/local/bin if writable,+# else ~/.local/bin)++set -eu++REPO="tracewayapp/traceway"+API="https://api.github.com/repos/${REPO}/releases"++err() { printf 'traceway-cli-install: error: %s\n' "$*" >&2; exit 1; }+log() { printf 'traceway-cli-install: %s\n' "$*"; }++command -v curl >/dev/null 2>&1 || err "curl is required"+command -v tar >/dev/null 2>&1 || err "tar is required"++UNAME_S="$(uname -s)"+UNAME_M="$(uname -m)"+case "$UNAME_S" in+ Linux) OS="linux" ;;+ Darwin) OS="darwin" ;;+ *) err "unsupported OS: $UNAME_S (Linux and macOS only; for Windows download the .zip from https://github.com/${REPO}/releases)" ;;+esac+case "$UNAME_M" in+ x86_64|amd64) ARCH="x86_64" ;;+ arm64|aarch64) ARCH="arm64" ;;+ *) err "unsupported arch: $UNAME_M" ;;+esac+log "detected $OS/$ARCH"++# CLI releases are tagged cli/vX.Y.Z; the same repo also publishes backend+# releases, so "latest" must be resolved by scanning tags, not /releases/latest.+VERSION="${TRACEWAY_CLI_VERSION:-}"+VERSION="${VERSION#v}"+if [ -z "$VERSION" ]; then+ VERSION="$(curl -fsSL "${API}?per_page=30" \+ | grep -o '"tag_name":[[:space:]]*"cli/v[^"]*"' \+ | head -1 | sed 's|.*cli/v||; s|"$||')"+ [ -n "$VERSION" ] || err "could not determine the latest CLI release from ${API}"+fi+log "installing traceway CLI v${VERSION}"++RELEASE_JSON="$(curl -fsSL "${API}/tags/cli%2Fv${VERSION}")" \+ || err "no CLI release found for v${VERSION} (see https://github.com/${REPO}/releases)"++TARBALL="traceway_${VERSION}_${OS}_${ARCH}.tar.gz"+URL="$(printf '%s' "$RELEASE_JSON" \+ | grep -o "\"browser_download_url\":[[:space:]]*\"[^\"]*/${TARBALL}\"" \+ | head -1 | sed 's|.*"\(https://[^"]*\)"|\1|')"+[ -n "$URL" ] || err "release v${VERSION} has no asset ${TARBALL}"+CHECKSUMS_URL="$(printf '%s' "$RELEASE_JSON" \+ | grep -o '"browser_download_url":[[:space:]]*"[^"]*/checksums\.txt"' \+ | head -1 | sed 's|.*"\(https://[^"]*\)"|\1|')"++TMP="$(mktemp -d)"+cleanup() { rm -rf "$TMP"; }+trap cleanup EXIT++log "downloading $URL"+curl -fsSL -o "${TMP}/${TARBALL}" "$URL" || err "failed to download $URL"++if [ -n "$CHECKSUMS_URL" ]; then+ log "verifying sha256"+ curl -fsSL -o "${TMP}/checksums.txt" "$CHECKSUMS_URL" \+ || err "failed to download checksums.txt"+ EXPECTED="$(awk -v f="$TARBALL" '$2==f || $2=="*"f {print $1}' "${TMP}/checksums.txt")"+ [ -n "$EXPECTED" ] || err "no checksum entry for $TARBALL in checksums.txt"+ if command -v sha256sum >/dev/null 2>&1; then+ ACTUAL="$(sha256sum "${TMP}/${TARBALL}" | awk '{print $1}')"+ elif command -v shasum >/dev/null 2>&1; then+ ACTUAL="$(shasum -a 256 "${TMP}/${TARBALL}" | awk '{print $1}')"+ else+ err "no sha256sum or shasum available on this host"+ fi+ [ "$EXPECTED" = "$ACTUAL" ] || err "checksum mismatch for $TARBALL (expected $EXPECTED, got $ACTUAL)"+fi++log "unpacking"+tar -xzf "${TMP}/${TARBALL}" -C "$TMP"+[ -f "${TMP}/traceway" ] || err "binary not found in $TARBALL (malformed release archive)"++if [ -n "${TRACEWAY_INSTALL_DIR:-}" ]; then+ BIN_DIR="$TRACEWAY_INSTALL_DIR"+ mkdir -p "$BIN_DIR" || err "cannot create $BIN_DIR"+elif [ -d /usr/local/bin ] && [ -w /usr/local/bin ]; then+ BIN_DIR="/usr/local/bin"+else+ BIN_DIR="${HOME}/.local/bin"+ mkdir -p "$BIN_DIR"+fi++log "installing → ${BIN_DIR}/traceway"+install -m 0755 "${TMP}/traceway" "${BIN_DIR}/traceway"++"${BIN_DIR}/traceway" version >/dev/null 2>&1 \+ || err "installed binary failed to run (${BIN_DIR}/traceway version)"++case ":${PATH}:" in+ *":${BIN_DIR}:"*) ;;+ *) log "note: ${BIN_DIR} is not on your PATH; add it to your shell profile" ;;+esac++log "done — installed $("${BIN_DIR}/traceway" version --output table)"+log "next: traceway login --url https://cloud.tracewayapp.com (or your own instance)"diff --git a/docs/pages/learn/_meta.json b/docs/pages/learn/_meta.jsonindex 7ec48422..a6067ce0 100644--- a/docs/pages/learn/_meta.json+++ b/docs/pages/learn/_meta.json@@ -15,6 +15,7 @@"logs": "Logs","alerts": "Alerts","sso": "SSO",+ "cli": "CLI","cli-auth": "CLI Authentication","mcp": "MCP Server","embedded-mode": "Embedded Mode",diff --git a/docs/pages/learn/cli.mdx b/docs/pages/learn/cli.mdxnew file mode 100644index 00000000..aeb6b280--- /dev/null+++ b/docs/pages/learn/cli.mdx@@ -0,0 +1,147 @@+# CLI++import { Callout } from "nextra/components";++`traceway` is a command-line client for the Traceway HTTP API — exceptions, logs, endpoints, tasks, traces, and metrics from a terminal. It is designed to be first-class for both humans (with `gh`-style ergonomics) and LLM agents invoking it via shell tools: JSON output when piped, stable error identifiers and exit codes, and nothing that hangs waiting for input. For a quick tour, see the [CLI product page](https://tracewayapp.com/product/cli).++## Installation++### One-line install (macOS, Linux)++```bash+curl -fsSL https://cli.tracewayapp.com/install.sh | sh+```++The installer detects your OS and architecture, downloads the latest CLI release from GitHub, verifies its sha256 checksum, and installs `traceway` to `/usr/local/bin` (when writable) or `~/.local/bin` — no sudo. Two environment variables tweak it: `TRACEWAY_CLI_VERSION` pins a version (e.g. `1.9.3`) and `TRACEWAY_INSTALL_DIR` overrides the target directory.++### Prebuilt binaries++Every release publishes prebuilt binaries at [github.com/tracewayapp/traceway/releases](https://github.com/tracewayapp/traceway/releases) under the matching `CLI vX.Y.Z` tag — the CLI version tracks the backend release. Download the archive for your platform (`traceway_<version>_<os>_<arch>.tar.gz`, or `.zip` on Windows), extract it, and put `traceway` on your `PATH`. This is also the route for Windows, which the install script doesn't cover.++### From source++The `cli/` directory of the [main repo](https://github.com/tracewayapp/traceway) ships a Nix dev shell with everything needed:++```bash+cd cli+nix develop+just build # produces ./bin/traceway+```++Or with vanilla Go:++```bash+go build -o bin/traceway ./cmd/traceway+```++Verify an installed binary with `traceway version` (source builds report `dev`).++## Quick start++```bash+# 1. log in — prints a URL + short code, you approve in the browser+traceway login --url https://cloud.tracewayapp.com++# 2. pick a project (one-time; future calls use it implicitly)+traceway projects list+traceway projects use <project-id>++# 3. ask questions+traceway exceptions list --since 24h+traceway logs query --since 1h --search "OutOfMemory"+traceway endpoints list --since 1h+traceway metrics query --name http.server.duration --aggregation avg --since 1h+```++The default `traceway login` runs a browser device flow with an auto-refreshing token, so you stay logged in for up to 90 days of inactivity. Password login (`--password`) and personal access tokens (`--token`) are also supported — see [CLI Authentication](/learn/cli-auth) for all three modes, and for what to use in CI.++## Commands++| Command | Purpose |+|---|---|+| `traceway login` | Authenticate and store a token (device flow, `--password`, or `--token`) |+| `traceway logout` | Revoke the session server-side and forget stored credentials |+| `traceway profiles {list,use}` | Manage multiple Traceway accounts/instances |+| `traceway projects {list,use}` | List or select the active project |+| `traceway exceptions list` | Recent grouped exceptions |+| `traceway exceptions show <hash>` | A single exception group + occurrences |+| `traceway exceptions occurrence <id> --recorded-at <t>` | A single occurrence by id (+ `sessionId` and recording) |+| `traceway exceptions archive <hash>...` | Archive one or more groups (mutating; needs `--yes` non-interactively) |+| `traceway exceptions unarchive <hash>...` | Unarchive (mutating; needs `--yes` non-interactively) |+| `traceway logs query` | Query logs with severity / service / search filters |+| `traceway endpoints list` | Per-endpoint p50/p95/p99 stats |+| `traceway endpoints show <id> --recorded-at <t>` | A single request (transaction) by id: spans + linked errors |+| `traceway tasks show <id> --recorded-at <t>` | A single background task run by id |+| `traceway ai-traces show <id> --recorded-at <t>` | A single AI trace by id + its conversation |+| `traceway sessions show <id> --started-at <t>` | A single session by id + the exceptions that fired in it |+| `traceway traces show <id> --recorded-at <t>` | A distributed trace: every service node sharing the id |+| `traceway metrics query` | Time-series metric queries |+| `traceway mcp` | Serve the [MCP server](/learn/mcp) over stdio |++Run `traceway <command> --help` for full per-command flags.++<Callout type="info">+ The `show` / `occurrence` commands take a UUID plus a **required** timestamp flag (`--recorded-at`, or `--started-at` for `sessions`). Telemetry tables are partitioned by day; the timestamp bounds the query so the lookup prunes partitions instead of scanning all of them. Get the id and its timestamp together — from a dashboard URL's `?t=` param, a notification's `Occurred at`, or a list row's `recordedAt`. Omitting the flag exits 2 (`usage_error`).+</Callout>++## Profiles++Multiple Traceway instances or accounts coexist via profiles. Configuration (URL, username) lives in `$XDG_CONFIG_HOME/traceway/config.json` so it can be checked in or managed declaratively; credentials and the active project live in `$XDG_STATE_HOME/traceway/state.json`.++```bash+traceway login --url https://traceway.example.com --profile work+traceway profiles list+traceway profiles use work+traceway --profile personal exceptions list # one-off override+```++## Output formats++The `--output` flag picks the format. The default is `table` on a TTY and `json` otherwise — piping always gets machine-readable output.++| Format | Use |+|---|---|+| `table` | Human-friendly columns (default on TTY) |+| `json` | Compact JSON, one record per line (default when stdout isn't a TTY) |+| `yaml` | YAML rendering of the same data |++`--fields a,b,c` projects list responses to just those keys:++```bash+traceway exceptions list --output json --fields exceptionHash,count,lastSeen+```++## Errors and exit codes++Every error writes a stable JSON envelope to stderr (in `json` / `yaml` modes — prose in `table` mode):++```json+{"error":"token_expired","message":"session expired or invalid","hint":"traceway login","exit_code":4}+```++The `error` field is a stable snake_case identifier that scripts and LLMs can branch on. Exit codes:++| Exit | Meaning |+|---|---|+| 0 | Success |+| 1 | Generic / API error |+| 2 | Usage error (bad flags, missing confirmation, invalid time range) |+| 3 | Connection failure |+| 4 | Auth failure (`not_authenticated`, `token_expired`, `forbidden`) |+| 5 | Not found |+| 6 | Rate limited |+| 7 | Server (5xx) |++## Mutations require confirmation++`exceptions archive` and `exceptions unarchive` are the only commands that change server state, and they require explicit consent:++- Pass `--yes` to skip the prompt.+- Or set `TRACEWAY_ASSUME_YES=1` in the environment.+- Or run interactively and answer the `Continue? [y/N]` prompt.++Calling a mutating command from a non-TTY context (script, LLM tool call) without one of the opt-ins fails immediately with `usage_error` (exit 2) — no hung prompts.++## MCP server++`traceway mcp` serves the whole query/debug surface as an MCP server on stdio for clients like Claude Code, Claude Desktop, and Cursor, reusing the CLI session and current project. See [MCP Server](/learn/mcp) for the stdio setup, the zero-install remote server every backend hosts at `/mcp`, and headless use via `TRACEWAY_URL` + `TRACEWAY_TOKEN`.diff --git a/website/app/product/cli/page.tsx b/website/app/product/cli/page.tsxnew file mode 100644index 00000000..b681f91d--- /dev/null+++ b/website/app/product/cli/page.tsx@@ -0,0 +1,306 @@+import Link from "next/link";+import type { Metadata } from "next";+import { SquareTerminal, Plug, ArrowRight } from "lucide-react";++import { Chip } from "@/components/chip";+import { FinalCTA } from "@/components/final-cta";+import { AuroraBackground } from "@/components/aurora-background";+import { Eyebrow } from "@/components/eyebrow";+import { Terminal } from "@/components/terminal";+import { CopyCommand } from "@/components/copy-command";+import { GITHUB_URL } from "@/lib/links";++export const metadata: Metadata = {+ title: "CLI · Traceway",+ description:+ "The traceway CLI brings your production exceptions, logs, endpoints, and metrics to the terminal. One binary, gh-style ergonomics for humans, JSON and stable exit codes for agents.",+};++export default function CliPage() {+ return (+ <main className="relative">+ <section className="hero hero-product relative">+ <AuroraBackground variant="hero" />+ <div className="wrap relative z-10">+ <div className="flex flex-col items-center text-center">+ <Chip>+ <SquareTerminal className="h-3 w-3 inline mr-1" />+ CLI+ </Chip>+ <h1 className="mt-6 max-w-[26ch]">+ Production telemetry, <em>in your terminal.</em>+ </h1>+ <p className="hero-sub text-pretty">+ Exceptions, logs, endpoints, and metrics as commands. Tables for+ humans on a TTY, JSON and stable exit codes for scripts and+ agents.+ </p>+ <div className="mt-8 w-full max-w-[640px]">+ <CopyCommand+ size="lg"+ className="w-full"+ command="curl -fsSL https://cli.tracewayapp.com/install.sh | sh"+ />+ </div>+ <p className="dim mt-5 font-mono text-[0.75rem]">+ Or grab a prebuilt binary for macOS, Linux, or Windows with every+ release.+ </p>+ <p className="mt-3 font-mono text-[0.6875rem] uppercase tracking-[0.08em]">+ <Link+ href="https://docs.tracewayapp.com/learn/cli"+ target="_blank"+ rel="noopener noreferrer"+ className="text-fg-2 hover:text-a2 transition-colors"+ >+ Read the CLI docs →+ </Link>+ </p>+ </div>+ </div>+ </section>++ <div className="band-light">+ <section className="wrap">+ <div className="feature-row">+ <div className="feat-copy">+ <Eyebrow>Installation</Eyebrow>+ <h2>+ One binary, <em>anywhere Go runs</em>+ </h2>+ <p>+ One command downloads the latest release for your platform,+ verifies its checksum, and puts <code>traceway</code> on your{" "}+ <code>PATH</code> — no sudo, no package manager. Windows+ archives ship with every release too.+ </p>+ <ul className="feat-bullets">+ <li>One-line installer for macOS and Linux</li>+ <li>Checksum-verified prebuilt binaries, Windows included</li>+ <li>Single static binary, no runtime dependencies</li>+ <li>CLI version tracks the backend release</li>+ </ul>+ </div>+ <Terminal+ title="bash · install"+ lines={[+ {+ ln: "1",+ type: "tx",+ content: (+ <>+ <span className="cmd">$</span> curl -fsSL+ https://cli.tracewayapp.com/install.sh | sh+ </>+ ),+ },+ {+ ln: "2",+ type: "mute",+ content: "# detected darwin/arm64 · sha256 verified",+ },+ {+ ln: "3",+ type: "tx",+ content: (+ <>+ <span className="cmd">$</span> traceway version+ </>+ ),+ },+ {+ ln: "4",+ type: "ok",+ content: "traceway version 1.9.3",+ },+ ]}+ />+ </div>+ </section>++ <section className="wrap">+ <div className="feature-row reverse">+ <div className="feat-copy">+ <Eyebrow>Usage</Eyebrow>+ <h2>+ Ask questions, <em>get answers</em>+ </h2>+ <p>+ Pick a project once, then query it like you'd query{" "}+ <code>gh</code>: grouped exceptions, log search, per-endpoint+ percentiles, metric time series. Output adapts to where it+ goes.+ </p>+ <ul className="feat-bullets">+ <li>Exceptions, logs, endpoints, tasks, traces, metrics</li>+ <li>Tables on a TTY, JSON when piped</li>+ <li>--fields trims responses to what was asked</li>+ <li>Stable error identifiers and exit codes</li>+ </ul>+ </div>+ <Terminal+ title="bash · traceway"+ lines={[+ {+ ln: "1",+ type: "tx",+ content: (+ <>+ <span className="cmd">$</span> traceway exceptions list+ --since 24h+ </>+ ),+ },+ {+ ln: "2",+ type: "mute",+ content: "HASH TYPE COUNT LAST SEEN",+ },+ {+ ln: "3",+ type: "mute",+ content: "82b58892 TypeError 412 2m ago",+ },+ {+ ln: "4",+ type: "tx",+ content: (+ <>+ <span className="cmd">$</span> traceway logs query --since+ 1h --search "OutOfMemory" | head -1+ </>+ ),+ },+ {+ ln: "5",+ type: "mute",+ content:+ '{"severity":"ERROR","service":"checkout-api","body":"OutOfMemory …"}',+ },+ {+ ln: "6",+ type: "ok",+ content: "# tables for you, JSON for your scripts",+ },+ ]}+ />+ </div>+ </section>++ <section className="wrap">+ <div className="feature-row">+ <div className="feat-copy">+ <Eyebrow>Authentication</Eyebrow>+ <h2>+ Log in once, <em>stay logged in</em>+ </h2>+ <p>+ <code>traceway login</code> opens a browser device flow: approve+ a short code on your instance and the CLI holds a token that+ refreshes itself. No password stored, nothing to paste.+ </p>+ <ul className="feat-bullets">+ <li>Browser device login with auto-refreshing tokens</li>+ <li>Stays signed in for up to 90 days of inactivity</li>+ <li>Personal access tokens for CI and headless boxes</li>+ <li>Profiles for multiple accounts and instances</li>+ </ul>+ </div>+ <Terminal+ title="bash · login"+ lines={[+ {+ ln: "1",+ type: "tx",+ content: (+ <>+ <span className="cmd">$</span> traceway login --url+ https://cloud.tracewayapp.com+ </>+ ),+ },+ {+ ln: "2",+ type: "mute",+ content: "# visit https://cloud.tracewayapp.com/device",+ },+ {+ ln: "3",+ type: "mute",+ content: "# and enter the code XKCD-2347",+ },+ {+ ln: "4",+ type: "ok",+ content: "✓ logged in as [email protected]",+ },+ {+ ln: "5",+ type: "tx",+ content: (+ <>+ <span className="cmd">$</span> traceway projects use+ checkout-api+ </>+ ),+ },+ ]}+ />+ </div>+ </section>++ <section className="wrap pb-16">+ <Link+ href="/product/mcp"+ className="group mx-auto flex max-w-3xl flex-col items-start gap-4 rounded-2xl p-8 transition-colors sm:flex-row sm:items-center sm:justify-between"+ style={{+ background: "var(--ink-0)",+ border: "1px solid var(--hair-2)",+ boxShadow:+ "0 1px 2px rgba(10,14,24,0.04), 0 12px 30px -18px rgba(10,14,24,0.14)",+ }}+ >+ <div className="flex flex-col gap-2">+ <div className="flex items-center gap-2">+ <Plug className="h-4 w-4 text-a2" />+ <span className="font-mono text-[0.6875rem] uppercase tracking-[0.14em] text-fg-3">+ Also available+ </span>+ </div>+ <p className="text-lg font-semibold text-fg-0">+ The same binary is an MCP server.+ </p>+ <p className="muted max-w-[48ch] text-pretty">+ Run <code>traceway mcp</code> and Claude Code, Claude Desktop,+ or Cursor get every query as a live tool, reusing your CLI+ login and current project.+ </p>+ </div>+ <span className="inline-flex shrink-0 items-center gap-1.5 font-mono text-[0.8125rem] text-a2 transition-transform group-hover:translate-x-0.5">+ Explore the MCP server+ <ArrowRight className="h-4 w-4" />+ </span>+ </Link>+ </section>+ </div>++ <FinalCTA+ title={+ <>+ Your next debugging session, <em>without leaving the shell.</em>+ </>+ }+ description="Install the CLI, log in, and query your production telemetry."+ primary={{+ label: "Start for free",+ href: "https://cloud.tracewayapp.com/register",+ }}+ secondary={{+ label: "Star on GitHub",+ href: GITHUB_URL,+ external: true,+ }}+ />+ </main>+ );+}diff --git a/website/app/product/mcp/page.tsx b/website/app/product/mcp/page.tsxindex e85428bb..156083ed 100644--- a/website/app/product/mcp/page.tsx+++ b/website/app/product/mcp/page.tsx@@ -189,6 +189,12 @@ export default function McpPage() {stdio. It reuses your CLI session and refreshes device-logintokens automatically.</p>+ <p>+ New to the CLI? Installation, usage, and login live on the{" "}+ <Link href="/product/cli" className="text-a2 hover:underline">+ CLI page →+ </Link>+ </p><ul className="feat-bullets"><li>One binary, no extra daemon</li><li>Reuses your CLI login and current project</li>