v0.1.0

FluxPoint CLI

Agent-first observability from your terminal

Installation

Install FluxPoint CLI with the one-line installer. It detects your platform and installs the matching binary.

One-line installer

curl -fsSL https://raw.githubusercontent.com/lommaj/FluxPoint/master/scripts/install.sh | sh

Verify installation

fluxpoint --version
# fluxpoint 0.1.0

Supported Platforms

OS	Architecture	Artifact
Linux	x64	`linux-x64`
Linux	arm64	`linux-arm64`
macOS	x64 (Intel)	`darwin-x64`
macOS	arm64 (Apple Silicon)	`darwin-arm64`

For Contributors: Build from source

Building from source is intended for local development and contribution workflows.

cargo install --path packages/fluxpoint-cli

Quick Start

Get up and running in under a minute. The CLI works against your local FluxPoint stack or a remote instance.

1. Connect an OTLP source

fluxpoint-cli connect otlp --language node

2. Ingest test data

fluxpoint-cli ingest --fixture test-data/sample.json

3. View recent signals

fluxpoint-cli signals --last 30m

4. Get agent-readable context

fluxpoint-cli context --last 1h

5. Connect a GitHub repo for code correlation

fluxpoint-cli connect github --repo owner/repo --token ghp_...

Commands

All commands support --output json for machine-readable output and --output table (default) for human-readable output.

Connect Sources

connect vercel --token <TOKEN>

Auto-configure a Vercel log drain. Sets up the integration so logs flow into FluxPoint automatically.

fluxpoint-cli connect vercel --token vrcl_... --vercel-project my-app

connect otlp --language <LANG>

Generate OTLP integration configuration for your language runtime. Supported: node, python, go, rust, generic.

fluxpoint-cli connect otlp --language node --ingestion-url http://localhost:8787

connect github --repo <OWNER/REPO> --token <TOKEN>

Connect a GitHub repository for code correlation. Enables tracing signals back to the exact commit and file.

fluxpoint-cli connect github --repo acme/api --token ghp_...

Observe

signals --last <DURATION>

Query signals from OpenSearch. Shows recent alerts, anomalies, and notable events in your infrastructure.

fluxpoint-cli signals --last 1h --project my-project --limit 20

context --last <DURATION>

Produce an agent-readable context summary with temporal pattern detection. Designed for AI agent consumption.

fluxpoint-cli context --last 30m --project my-project

Analyze

correlate --trace-id <ID>

Correlate a trace to logs and code locations. Maps runtime errors to source files with confidence scores.

fluxpoint-cli correlate --trace-id abc123 --min-confidence 0.7

rca --trace-id <ID>

Deterministic root cause analysis for a trace. Synthesizes logs, correlations, and graph data into an RCA report.

fluxpoint-cli rca --trace-id abc123 --output json

graph --trace-id <ID>

Build graph traversal payloads from trace context. Produces structured data for dependency analysis.

fluxpoint-cli graph --trace-id abc123

Data

ingest --fixture <PATH>

Load deterministic fixture data into local CLI state. Useful for testing and demos.

fluxpoint-cli ingest --fixture test-data/scenario.json --push-backend --tenant-id my-tenant

query horizons

List horizon entries from local state or backend. Shows a timeline view of ingested data.

fluxpoint-cli query horizons --limit 10

query context --trace-id <ID>

Inspect context for a specific trace from local state or backend.

fluxpoint-cli query context --trace-id abc123

query billing

View billing ledger and checkpoint summary from fixture state.

fluxpoint-cli query billing --limit 20

Output Formats

Every command supports two output modes via the global --output flag.

Table output (default, for humans)

$ fluxpoint-cli signals --last 1h --output table

SIGNALS (last 1h)
ID        SEVERITY  PROJECT     MESSAGE                    TIMESTAMP
sig-001   error     api-prod    500 rate spike detected    2024-01-15T10:23:00Z
sig-002   warning   web-app     Latency p99 > 2s          2024-01-15T10:21:00Z
sig-003   info      worker      Queue depth normalizing    2024-01-15T10:18:00Z

JSON output (for agents and scripts)

$ fluxpoint-cli signals --last 1h --output json

{
  "signals": [
    {
      "id": "sig-001",
      "severity": "error",
      "project": "api-prod",
      "message": "500 rate spike detected",
      "timestamp": "2024-01-15T10:23:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "window": "1h",
    "query_time_ms": 42
  }
}

Configuration

The CLI can operate in three data source modes, controlled by the global --source flag.

Flag	Description
`--source auto`	Default. Uses backend if `--api-url` is set, otherwise falls back to local state.
`--source state`	Force local fixture state from `fluxpoint-state.json`.
`--source backend`	Force API calls. Requires `--api-url` and `--api-key`.

Global Options

--api-url <URL>

FluxPoint API base URL (e.g., https://app.fluxpoint.dev). Enables backend mode when source=auto.

--api-key <KEY>

API key for authenticated backend routes. Required when using backend mode.

--state-file <PATH>

Path to local JSON state file for deterministic fixture workflows. Defaults to ./fluxpoint-state.json.

--output <FORMAT>

Output format: table (default, human-readable) or json (machine-readable).

Example: connecting to a remote FluxPoint instance

fluxpoint-cli --api-url https://app.fluxpoint.dev --api-key fp_... signals --last 1h