zero

Your ZeroNoise research, in your terminal.

Unofficial CLI · macOS Apple Silicon · Developer preview

Pull cited research into files. Curate sources. Configure and operate your agents.

Unofficial, independently developed, and not affiliated with or endorsed by ZeroNoise. This client uses observed web-app HTTP/LiveView behavior, not a promised public API. Provider changes can break individual commands. The name and logo belong to ZeroNoise. The logo identifies the service this CLI connects to.

Start here

The macOS archive includes its own runtime. No Node.js or npm installation is needed. The first build targets Apple Silicon. Intel Macs are not verified.

Download zero-macos-arm64.tar.gz and SHA256SUMS from the Releases page. Keep both files in the same directory:

shasum -a 256 -c SHA256SUMS
tar -xzf zero-macos-arm64.tar.gz
./zero-macos-arm64/zero --help

Keep the extracted folder together. Move the entire folder to a permanent location and add that folder to your PATH. Until then, use ./zero-macos-arm64/zero in place of zero.

This preview is not Developer ID signed or notarized. macOS may block a downloaded executable. Review the source and checksum before approving it in macOS security settings. Do not disable Gatekeeper globally.

Authenticate once with zero auth login --timeout 120000. The optional login flow uses your consented macOS Chrome connection; see the authentication instructions. Normal commands use a protected saved-cookie file and do not automate a browser. An existing ZeroNoise account and appropriate access are required.

zero doctor --json
zero status
zero agents list --limit 20 --json
zero pull EXACT-AGENT-SLUG --out ./research --timeout 60000 --json

The pull writes original brief Markdown, supporting documents, local citation links and a manifest. Stdout returns a small receipt. Rerun against the same directory to reconcile interrupted work and reuse unchanged files.

What works

Job	Commands
Find and inspect	workspaces list, agents list/resolve/get, capabilities
Retrieve research	briefs list/latest/get/details/export, documents list/get, insights list, pull
Curate sources	sources list/export/add/import/plan/apply/reconcile/remove, suggestions list/approve/reject
Configure agents	agents export/validate/diff/update/schedule
Manage lifecycle	agents create/activate/pause/duplicate
Run research	sources discover/sync, conditional briefs generate
Observe activity	status, operations inspect/get/wait, usage, usage list

Use zero RESOURCE COMMAND --help for exact arguments.

See where to pick up

zero status                                    # Active agents and latest observed briefs
zero status --all                              # Include paused and inactive agents
zero status --agent EXACT-AGENT-SLUG              # Schedule, source counts and visible progress
zero status --agent EXACT-AGENT-SLUG --usage      # Add this month's usage
zero status --json                              # Structured snapshot for agents
zero status --out ./status.json                 # Save the snapshot; print a small receipt

The overview checks at most 10 agents by default. Increase --limit up to 100. It selects from the initial observed inventory, not a guaranteed complete account list. Unknown lifecycle values remain visible. Agent names never decide filtering. Active means configured active, not healthy. No visible progress means unknown, not idle or completed. Brief dates do not establish delivery or read status.

Status performs read-only HTTP and LiveView requests within the command timeout. It does not download article bodies, generate research, or open a browser. Unavailable sections retain safe error codes without discarding successful reads. Partial snapshots return exit 1 and still support --json and --out. See the status contract for coverage details.

Understand spending

zero usage                                      # Personal account, this month
zero usage --agent EXACT-AGENT-SLUG               # Provider totals and schedule estimate
zero usage --since 7d --details                  # Recent accounting rows
zero usage --since 7d --out ./usage.json          # JSON file and a small receipt
zero usage --json                                # Structured summary for agents

The summary includes observed spending by agent, brief versus setup costs, the newest observed run and current billing information. Supported trial billing shows remaining allowance, expiry and the reported paid-billing start date. Agent summaries include the provider's date-scoped totals and a rough 30-day estimate when the active schedule and sampled run costs are available.

Account history is an initial HTTP snapshot, currently capped by the provider. Row subtotals are labelled as observed, potentially incomplete amounts, never as the full account bill. --limit bounds both summary inputs and detail rows. Narrow the date window to focus on recent activity. All usage commands read over HTTP with saved cookies; they do not start research or open a browser.

Review, then apply

zero agents diff EXACT-AGENT-SLUG --file ./agent.json --json
zero agents update EXACT-AGENT-SLUG --file ./agent.json --apply --json
zero sources add --agent EXACT-AGENT-SLUG --url https://example.com/feed-a --url https://example.com/feed-b --json
zero sources import --agent EXACT-AGENT-SLUG --file ./sources.txt --json

Writes preview by default. --apply submits; commands named apply are already explicit write intent. Work that may incur charges also requires --allow-usage. Cost is reported as unknown, never assumed free.

Repeat --url to submit up to 100 sources in one provider batch. For longer or reviewable input, use sources import with one URL per line. A batch is submitted once and reconciled per URL; an unknown receipt must be reconciled, never replayed. ZeroNoise may normalize a URL into a channel whose inventory row omits the original URL. In that case the CLI reports the per-input outcome as unknown even when the aggregate source count increased; it does not turn that count into a false success receipt.

zero briefs generate --agent EXACT-AGENT-SLUG --apply --allow-usage --wait --timeout 60000 --json
zero operations inspect --agent EXACT-AGENT-SLUG --json

Generation requires the provider's Get today's brief control to be available. It creates a provider-labelled preview brief; it does not change the schedule or replace an existing post. During the same invocation, --wait can observe the new result. Missing progress panels do not prove completion.

Boundaries

• No durable standalone sync polling or verified monitoring-scope editor.
• Creation currently targets the observed personal workspace.
• Session expiry requires explicit reauthentication; long-lived refresh is unverified.
• Evidence covers documents reachable from selected briefs, not the entire scanned corpus.
• Partial or ambiguous outcomes return nonzero status and preserve available results.
• Cookies and private research belong outside the repository. Never paste them into issues.

See current status for the verification boundary.

Documentation

• Command reference: auth, arguments, files, errors and recovery.
• Agent workflow: bounded reads, reviewed writes and finish checks.
• Examples: minimal agent configuration; manage sources separately.
• Contributing and security.

Development and distribution

npm ci
npm test
node scripts/package-macos.mjs

Development requires Node.js 22 and npm. The packaging script runs on an Apple Silicon Mac, checks the official Node runtime checksum, and tests the launcher without Node on PATH.

Tests exercise CLI commands against controlled fixtures; live checks are separate. Packing builds first and includes only runtime files, public-facing guides and generic examples, excluding internal research and acceptance notes.

This repository contains the public CLI source and synthetic test fixtures. Private development history, account records and research exports are not included. Installation uses the macOS archive; npm publishing is disabled. The CLI code is MIT licensed. Bundled dependencies retain their own licenses. ZeroNoise branding is not covered by the CLI's license.