Headless Investigations
The neubird run and neubird investigate commands run AI-powered analyses from the command line without the interactive TUI. Designed for programmatic invocation by external tools, CI pipelines, and coding agents like OpenClaw.
Usage
neubird run <capability> --project <name>
neubird run health --project prod_cop
neubird run cost 7d --project prod_cop
neubird investigate "any 403s in the last hour?" --project prod_cop
Findings are printed as markdown to stdout, ending with a Completed in Xs sentinel line. Stderr is used only for errors and the spinner during investigation.
# Save findings to a file
neubird run health --project prod_cop > health-report.md
# Free-form investigation
neubird investigate "what caused the latency spike?" --project prod_cop > findings.md
Capabilities
neubird run exposes named analysis types:
| Capability | Description | Default lookback |
|---|---|---|
health |
Full infrastructure health sweep | 1 hour |
cost |
Cloud cost baseline + 24h spend projection | 24 hours |
investigate |
Free-form investigation prompt | — |
performance |
Find latency outliers and slow queries | 1 hour |
predict |
What could go wrong in the next 24h? | — |
deep-dive |
Full health sweep with extended context | 24 hours |
silent-failures |
Find quietly degrading services | — |
change-risk |
Assess risk from recent deployments | 24 hours |
blast-radius |
Map dependency chains and cascade risk | — |
Capabilities that accept a lookback window can be customized: neubird run health 4h, neubird run cost 7d.
neubird investigate "<prompt>" is an alias for neubird run investigate "<prompt>".
Flags
| Flag | Default | Description |
|---|---|---|
--project |
— | Project to investigate (name or UUID). Required on first call. |
--timeout |
120 |
Investigation timeout in seconds (health/cost/deep-dive enforce 300s minimum) |
--session |
— | Session file for multi-turn conversations (path or directory) |
--cleanup |
false |
Delete a session file and exit |
--verbose |
false |
Show tool calls, progress markers, and MCP server logs on stderr |
--format |
markdown |
Output format |
--profile |
unnamed | Login profile (set via global neubird --profile <name>) |
Multi-turn sessions
Use --session to persist conversation history across invocations, enabling follow-up questions:
# First turn — auto-generates session file in /tmp/
neubird run health --project prod_cop --session /tmp/
# stderr: Session: /tmp/nb-1743620000000.json
# Follow-up — agent has full context from the health sweep
neubird investigate "drill into the RDS memory alarm" --session /tmp/nb-1743620000000.json
# Clean up
neubird investigate --cleanup --session /tmp/nb-1743620000000.json
Session files store conversation history and cached schema context. Follow-up calls skip schema discovery, saving ~15-20 seconds. The --project flag is inherited from the session on follow-ups.
When --session points to a directory, a new session file (nb-<timestamp>.json) is auto-generated. The resolved path is printed to stderr so callers can capture it.
Discovering projects
Use neubird projects to list available projects for the current login profile:
neubird projects
PROJECT ID
prod_cop ed9e59e3-a843-4a14-8afd-8e3975aef71d
staging_auto 11598cd2-fd50-49c7-8b57-02de7ab1d689
dev_cop a322dffc-476f-4e5d-8669-fe7e5044dd4c
Both the project name and UUID work with --project.
Exit codes
| Code | Meaning |
|---|---|
0 |
Investigation complete, findings on stdout |
1 |
Investigation failed or timed out |
2 |
Not authenticated — run neubird login |
3 |
No connected environment found |
How it works
- Authenticate — loads credentials from the saved login profile
- Connect — connects to the specified project via NeuBird's ACE engine
- Discover — scans the project's telemetry schema (cached in session files for follow-ups)
- Investigate — runs the same agentic investigation loop as the interactive TUI
- Report — prints structured markdown findings to stdout
The investigation uses the same AI engine, tools, and skills as interactive sessions. For health and cost sweeps, findings are handed off to a senior-level synthesis pass before output. See Agentic Investigations for details on how the investigation loop works.
Example invocations
# Infrastructure health
neubird run health --project prod_cop
neubird run health 4h --project prod_cop
# Cost analysis
neubird run cost --project prod_cop
neubird run cost 7d --project staging_auto
# Free-form investigation
neubird investigate "the checkout service is throwing 503s" --project prod_cop
neubird investigate "pods in payments namespace are CrashLoopBackOff" --project staging_auto
# Predictive and risk analysis
neubird run predict --project prod_cop
neubird run change-risk --project prod_cop
neubird run silent-failures --project prod_cop