bybit-analysis

Install

Local development

bun install

Global install from npm

npm i -g bybit-analysis

This package uses Bun at runtime, so Bun must be installed on the machine where you run the CLI.

Run

Local source run

bun run src/index.ts <command> [options]

Installed CLI

bybit-analysis <command> [options]

When .env and .bybit-profiles.json live in a workspace directory rather than the current shell directory, pass --project-root <path>.

bybit-analysis summary --project-root workspace/skills/bybit-analysis --profile main --window 30d

Command-specific help:

bun run src/index.ts <command> --help
bybit-analysis <command> --help

Exchange Readiness Status

• Shared domain entities use extensible exchange identifiers (no hardcoded exchange: "bybit" contract in core types).
• Exchange-specific DTO mapping/normalization lives under src/services/bybit/normalizers.
• Composition root is provider-based via src/services/composition/createServiceBundle.ts.
• Provider contract is capability-based (supportedMarketCategories, supportedSourceModes, botData) and exposed in ServiceBundle.
• Shared request/config contracts keep provider payloads in generic providerContext; runtime config now carries explicit exchangeProvider; Bybit bot strategy IDs live under providerContext.bybit.botStrategyIds.
• botService is optional in ServiceBundle and only required by providers that expose bot capability.
• Current implementation status: only the bybit provider is implemented and registered.
• This is not full multi-exchange support yet; it is a structural split so new providers can be added without rewriting shared domain models.

Exit Codes (Automation Contract)

• 0 complete success (and for health, connectivity/auth checks passed)
• 3 optional partial success (report generated, but only optional enrichment/data degraded)
• 4 critical incomplete analytics (report generated, but output is not safely actionable for automation; expected spot-intrinsic unsupported exposure/risk reports stay successful)
• 5 health-check failure (health command returned failed connectivity and/or auth)
• 1 runtime failure (unexpected execution error)
• 2 usage/config failure (invalid args or runtime validation error)

Automation should branch on exit code only; no prose parsing is required.

Testing

# unit + integration suite
bun run test

# watch mode during development
bun run test:watch

# optional local coverage report
bun run test:coverage

# standard local gate (types + tests + build)
bun run verify

# release validation before tag/release
bun run validate:local-release

Current suite covers production-critical paths: spot PnL normalization, pagination safety handling, secret redaction, CLI stdout/stderr contract, all report schema contracts, and CLI smoke/integration flow.

CI / release flow

• CI workflow: .github/workflows/verify.yml
• npm publish workflow: .github/workflows/npm-publish.yml
• CI runs on pull requests, pushes to main, version tags v*, and can be started manually with workflow_dispatch
• npm publish is triggered by GitHub Release published and validates release.tag_name == v<package.json.version>
• npm publish requires NPM_TOKEN in the new public GitHub repository secrets

npm release steps

1. Bump package.json.version.
2. Commit and push changes to the new public repository.
3. Create and push tag v<version>.
4. Publish a GitHub Release from that tag.
5. GitHub Actions publishes bybit-analysis to npm with the latest tag.

Open-source publication safety

Before publishing this project publicly:

1. Create a new public GitHub repository.
2. Copy or clean-push only the current working tree.
3. Do not migrate old git history from this private repository.
4. Run bun run validate:local-release before creating the release tag.
5. Verify npm pack --dry-run contains only intended package files.

Do not publish local secret material such as .env, .bybit-profiles.json, .openclaude-profile.json, tarballs, or ad-hoc local logs.

Commands

• summary - Period analytics summary (explicitly mixes period metrics with current snapshot context)
• balance - Live wallet/equity/margin balances
• pnl - Period PnL analysis
• positions - Live open position inventory and status
• exposure - Live exposure and concentration analysis
• performance - Period ROI and capital efficiency analysis
• risk - Live leverage and downside risk analysis
• bots - Optional bot/copy-trading analytics
• permissions - Live API key permission diagnostics
• config - Effective runtime config (redacted)
• health - Live API/connectivity/readiness checks

Markdown Schema Contracts (All Commands)

All commands now expose schema-stable Markdown contracts:

• Report-level Schema: <command>-markdown-v1 is present for every command.
• Report metadata lines are fixed and ordered: Generated at, As Of (for live snapshot reports when available), Schema, Command, Outcome, Exit Code, Data Completeness, Health Status, Source Freshness.
• Every section has a fixed id and is rendered as ## [section.id] Title.
• Section order and section type are fixed per command contract.
• Sections are never removed because of missing data; reports use deterministic placeholders (<empty> table rows), N/A, 0, unsupported, or info alerts.
• Data Completeness is a fixed section in every command contract:
  • Data-backed commands render merged completeness issues in that section.
  • Non data-backed commands (for example config, health, permissions) render explicit unsupported completeness status.
• Data Completeness states are machine-classified as complete, partial_optional, partial_critical, unsupported, or failed.

Summary Markdown Contract (summary-markdown-v1)

summary now uses a schema-stable section contract across market categories (linear, spot) and source modes (market, bot).

• Section IDs are fixed and rendered in headings as ## [section.id] Title.
• Section order and section type are fixed.
• Section typing is pinned by explicit section contract mapping (id + title + type), not inferred from payload data.
• Missing category-specific data is represented as empty rows / zero values / info alerts, not by omitting sections.
• summary.alerts is always alerts; if a tabular/alternative representation is needed, it must use a different section ID and title.
• Bot enrichment failure policy:
  • --source market: bot summary is optional enrichment. Failures do not abort report generation, but are surfaced explicitly in summary.alerts and summary.data_completeness with the original error reason.
  • --source bot: bot summary is required input. Bot fetch failures are fail-fast and abort summary generation.

Report-level metadata:

• Schema: summary-markdown-v1 line is present in output.

Fixed section order:

1. summary.contract (text)
2. summary.overview (kpi)
3. summary.activity (kpi)
4. summary.allocation (kpi)
5. summary.exposure (kpi)
6. summary.risk (kpi)
7. summary.open_positions (table)
8. summary.top_holdings (table)
9. summary.symbol_pnl (table)
10. summary.bots (table)
11. summary.alerts (alerts)
12. summary.data_completeness (alerts)

Spot PnL Inventory Method

• Cost basis method: weighted_average.
• Opening inventory at --from is reconstructed from pre-window spot executions (lookback: last 365 days) for symbols sold inside the window.
• If sell quantity cannot be matched to reconstructed inventory, the report is marked dataCompleteness.state=partial_optional, and unmatched quantity is excluded from realized PnL (no fallback to sell execution price).

PnL ROI Contract

• pnl uses explicit ROI status: supported or unsupported.
• ROI is supported only when both start and end equity are available.
• Start equity is resolved from account.equityHistory using the latest sample at or before --from.
• If start equity is unavailable, ROI KPI is rendered as unsupported, and the report includes an explicit reason in ROI Status.
• In the current Bybit account snapshot flow, historical equity is not fetched from a dedicated endpoint, so ROI/capital efficiency are explicitly marked unsupported.

Example (pnl section):

## ROI Status
- Status: unsupported
- Reason: no equity sample found at or before period start

Global Options

• --project-root <path>
• --profile <name>
• --profiles-file <path>
• --exchange-provider <bybit>
• --category <linear|spot>
• --source <market|bot>
• --fgrid-bot-ids <id1,id2,...>
• --spot-grid-ids <id1,id2,...>
• --format <md|compact|json>
• --from <ISO8601> period commands only: summary, pnl, performance, bots
• --to <ISO8601> period commands only: summary, pnl, performance, bots
• --window <7d|30d|90d> period commands only: summary, pnl, performance, bots
• --timeout-ms <number>
• --positions-max-pages <number>
• --executions-max-pages-per-chunk <number>
• --pagination-limit-mode <error|partial>
• --no-env
• --help, -h

Config & Environment Contract

Supported env vars:

• BYBIT_API_KEY
• BYBIT_SECRET
• BYBIT_API_SECRET
• BYBIT_ALLOW_INSECURE_CLI_SECRETS
• BYBIT_DISABLE_ENV
• BYBIT_PROFILE
• BYBIT_PROFILES_FILE
• BYBIT_EXCHANGE_PROVIDER
• BYBIT_CATEGORY
• BYBIT_SOURCE_MODE
• BYBIT_FGRID_BOT_IDS
• BYBIT_SPOT_GRID_IDS
• BYBIT_FORMAT
• BYBIT_TIMEOUT_MS
• BYBIT_WINDOW
• BYBIT_POSITIONS_MAX_PAGES
• BYBIT_EXECUTIONS_MAX_PAGES_PER_CHUNK
• BYBIT_PAGINATION_LIMIT_MODE
• BYBIT_CONFIG_DIAGNOSTICS

Precedence rules:

• General runtime fields: CLI args -> profile (if applicable) -> env -> defaults
• --project-root changes where .env and the default .bybit-profiles.json are resolved from; absolute --profiles-file paths are still used as-is.
• Exchange/provider selection is explicit via --exchange-provider / BYBIT_EXCHANGE_PROVIDER (currently only bybit is supported).
• Credentials: profile env references -> env -> legacy CLI flags (only with BYBIT_ALLOW_INSECURE_CLI_SECRETS=1) -> defaults
• Time range: --from + --to -> --window -> BYBIT_WINDOW -> default 30d window
• Live snapshot commands reject explicit historical intent from --from, --to, --window, and BYBIT_WINDOW
• Ambient env loading can be disabled with --no-env or BYBIT_DISABLE_ENV=1

Legacy hidden aliases are intentionally removed and not supported:

• WINDOW
• DEFAULT_CATEGORY
• DEFAULT_FORMAT
• DEFAULT_TIMEOUT_MS

CLI parsing conventions:

• Value options support both --flag value and --flag=value.
• -- stops option parsing; everything after is treated as positional arguments.
• Repeated scalar options use last-value-wins semantics.
• Repeatable list options --fgrid-bot-ids and --spot-grid-ids append values in argument order.

Parser strategy:

• The project keeps a custom parser for now to preserve strict, predictable behavior and zero runtime dependencies.
• Behavior is locked with table-driven tests in src/cli/parseArgs.test.ts.

Output formats:

• md - standard Markdown layout.
• compact - lossless Markdown layout with tighter spacing (presentation-only; no row/text truncation).
• json - versioned machine-readable envelope with report metadata, outcome classification, source freshness, stable sections, and structured data.

JSON Contract

• --format json emits report-json-v1.
• JSON includes:
  • jsonSchemaVersion
  • reportSchemaVersion
  • command, title, generatedAt, asOf
  • outcome (status, exit code, label, completeness class, health status)
  • dataCompleteness
  • sources
  • sections
  • data with machine-usable numeric/report payloads
• sources entries expose provider/exchange context, kind, fetchedAt, optional capturedAt, optional exchangeServerTime, optional period window, and cache status when known.

Credentials (Secure Default)

Recommended production paths:

• Environment variables (BYBIT_API_KEY + BYBIT_SECRET or BYBIT_API_SECRET)
• Explicit env-file launch, for example bun --env-file=.env run src/index.ts ...
• Profile-based env references (--profile + --profiles-file with apiKeyEnv / apiSecretEnv)
• OS secret store -> export to env before launch

Example (.env used explicitly via bun --env-file=.env ...):

BYBIT_API_KEY=xxx
BYBIT_SECRET=yyy

Legacy path (deprecated, insecure):

• --api-key and --api-secret are disabled by default because command-line secrets can leak via shell history, process listing, and command logging.
• Temporary bypass only: set BYBIT_ALLOW_INSECURE_CLI_SECRETS=1.

Config Priority

• General runtime fields: CLI args -> profile (if applicable) -> env -> defaults
• Credentials only: profile env references -> env -> legacy CLI flags (only with BYBIT_ALLOW_INSECURE_CLI_SECRETS=1) -> defaults
• Repo-local .env is not auto-loaded; the repository sets bunfig.toml with env = false for hermetic CLI/test runs.
• Use --no-env or BYBIT_DISABLE_ENV=1 when you need deterministic argv-only resolution even if the parent process exported BYBIT_* vars.

Credential Profiles

Use profiles to keep non-secret runtime settings plus env variable names for each account and switch by name:

bun run src/index.ts summary --profile subaccount-a

Default profiles file is ./.bybit-profiles.json (or set BYBIT_PROFILES_FILE / --profiles-file).

Profiles must not contain plaintext secrets. Use apiKeyEnv and apiSecretEnv to point at exported env variable names for that profile.

Example:

{
  "subaccount-a": {
    "apiKeyEnv": "SUBACCOUNT_A_API_KEY",
    "apiSecretEnv": "SUBACCOUNT_A_API_SECRET"
  },
  "subaccount-b": {
    "apiKeyEnv": "SUBACCOUNT_B_API_KEY",
    "apiSecretEnv": "SUBACCOUNT_B_API_SECRET",
    "category": "linear",
    "sourceMode": "bot",
    "futuresGridBotIds": ["612330315406398322"]
  }
}

Bot Mode In CLI

You can run built-in reports against grid bots by setting:

• --source bot
• --category linear|spot (optional; default linear)
• --fgrid-bot-ids <id1,id2,...> for Futures Grid bots
• --spot-grid-ids <id1,id2,...> for Spot Grid bots

Those bot identifiers are resolved in the Bybit adapter layer and mapped into provider request context. Provider selection is explicit via --exchange-provider bybit (or BYBIT_EXCHANGE_PROVIDER=bybit):

• providerContext.bybit.botStrategyIds.futuresGridBotIds
• providerContext.bybit.botStrategyIds.spotGridBotIds

Or set bot IDs once via env:

• BYBIT_FGRID_BOT_IDS=<id1,id2,...>
• BYBIT_SPOT_GRID_IDS=<id1,id2,...>

Pagination safety (optional):

• BYBIT_POSITIONS_MAX_PAGES=<number>
• BYBIT_EXECUTIONS_MAX_PAGES_PER_CHUNK=<number>
• BYBIT_PAGINATION_LIMIT_MODE=<error|partial>

Example:

bun run src/index.ts summary \
  --source bot \
  --fgrid-bot-ids 612330315406398322 \
  --spot-grid-ids 612340768081708828

Permissions check:

bun run src/index.ts permissions

Security note: config and permissions outputs are redacted for logs/CI and do not print raw API keys, API secrets, or full IP whitelist values.