Quickstart | CLI Overview | Command Reference | Configuration

---

Why Polaris

• Browse remote source and market datasets from the terminal
• Sync only the snapshot ranges you need
• Materialize full UTC-day local files automatically when a day is fully present
• Inspect the local dataset tree managed by Polaris
• Automate data workflows with plain CLI output or --json

Quickstart

1. Install Polaris

curl -fsSL https://github.com/polaris-data/cli/releases/latest/download/install.sh | sh

The installer downloads a verified standalone executable for macOS or Linux. It installs to $HOME/.local/bin by default and does not modify your shell profile. Set POLARIS_INSTALL_DIR or INSTALL_DIR to choose another destination.

Windows users can install from PowerShell:

irm https://github.com/polaris-data/cli/releases/latest/download/install.ps1 | iex

To install a specific tagged version, use that release's installer:

curl -fsSL https://github.com/polaris-data/cli/releases/download/v0.8.3/install.sh | sh

The standalone executable includes its runtime, so Node.js and Bun are not required.

The release asset URL is stable and always resolves to the latest release:

curl -fsSL https://github.com/polaris-data/cli/releases/latest/download/install.sh | sh

2. Optional: Set up your agent

Prompt your agent:

Skills (recommended)

Run `polaris skills add`, then show me how to browse and download market datasets with Polaris.

MCP

Run `polaris mcp add`, then show me how to browse and download market datasets with Polaris.

3. Browse via TUI

polaris

4. Browse remote datasets

polaris catalog --source hyperliquid --market BTCUSDT

5. Download one time range

polaris download \
  --source hyperliquid \
  --market BTCUSDT \
  --from 2026-06-01T00:00:00Z \
  --to 2026-06-02T00:00:00Z

6. Inspect local data

polaris list --source hyperliquid --market BTCUSDT

After download completes, Polaris stores the fetched snapshot files under its managed local root.

7. Optional: Sign in for more datasets

To sign in with the browser flow and save the returned API key locally:

polaris login

To enter an API key manually and save it locally:

polaris key

Or set it per-session:

export POLARIS_API_KEY="your_api_key"

Check whether Polaris sees a configured credential:

polaris account

8. Build from source

pnpm install
pnpm build:ts

Building from source requires Node.js 22+.

CLI Overview

polaris
├── account
├── catalog
├── completions
├── feedback
├── key
├── login
├── list
├── mcp
├── download
├── reset
└── skills

Top-level help:

polaris --help

Built-in integrations:

• polaris completions generates shell completion scripts
• polaris mcp exposes MCP registration helpers such as add and doctor
• polaris skills exposes skill sync helpers such as add and list

Command Reference

polaris

Opens the interactive remote dataset browser TUI in a real terminal. If no TUI can be rendered, it falls back to plain CLI output.

polaris login

Starts the browser login flow, waits for approval, and stores the returned Polaris API key in persistent credential storage.

polaris login

polaris key

Prompts securely for a Polaris API key and stores it in persistent credential storage.

polaris key

polaris account

Prints the current Polaris auth state, credential source, and live account details when signed in.

polaris account

polaris catalog

Lists remote datasets available from Polaris.

polaris catalog --json

polaris catalog \
  --source aster \
  --market BTCUSDT \
  --search btc \
  --limit 25

polaris feedback

Sends product feedback to the Polaris team through the configured Polaris API.

polaris feedback "can you add parquet downloads?"

polaris list

Lists local snapshots under the configured root.

polaris list --json

polaris download

Downloads missing snapshots for the requested dataset and time range. Existing complete local files are reused and not downloaded again.

After download completes, the fetched snapshots are stored under data/ within the configured local root.

polaris download \
  --source aster \
  --market BTCUSDT \
  --from 2026-06-01T00:00:00Z \
  --to 2026-06-02T00:00:00Z

polaris download \
  --source aster \
  --market BTCUSDT \
  --from 2026-06-01T00:00:00Z \
  --to 2026-06-02T00:00:00Z \
  --json \
  --concurrency 8

polaris reset

Removes all local dataset state managed by Polaris under the configured root and clears saved bookmarks.

polaris reset
polaris reset --json

polaris --update

Updates an Incur-built standalone executable to the highest compatible stable GitHub release. Polaris verifies the release asset's SHA-256 digest before replacing the current executable.

polaris --update

Package-manager and source installations do not enable binary self-updates.

Configuration

Environment variables

Variable	Default	Purpose
POLARIS_BASE_URL	https://api.polaris.supply	Base URL for Polaris API requests
POLARIS_API_KEY	unset	Optional bearer token for authenticated Polaris requests
POLARIS_ROOT	platform app-data directory	Override the local dataset root directory
POLARIS_CONCURRENCY	unset	Default download concurrency when --concurrency is not provided
POLARIS_TIMEOUT_SECS	unset	Request timeout in seconds

POLARIS_API_KEY takes precedence over the stored credential saved by polaris login or polaris key.

Example:

export POLARIS_BASE_URL="https://api.polaris.supply"
export POLARIS_ROOT="$HOME/.local/share/polaris-dev"
export POLARIS_CONCURRENCY="8"
export POLARIS_TIMEOUT_SECS="60"

polaris catalog
polaris list
polaris download --source aster --market BTCUSDT --from 2026-06-01T00:00:00Z --to 2026-06-02T00:00:00Z

Compatibility notes:

• TICK_ROOT, TICK_CONCURRENCY, and TICK_TIMEOUT_SECS are still accepted
• If POLARIS_API_KEY is unset, Polaris also falls back to the legacy tick OS credential entry when needed

JSON and automation

Use --json when you want structured output for scripts or agents.

Commands with --json support:

• polaris catalog
• polaris list
• polaris download
• polaris reset

Examples:

polaris catalog --json
polaris list --json
polaris download --source aster --market BTCUSDT --from 2026-06-01T00:00:00Z --to 2026-06-02T00:00:00Z --json
polaris reset --json

Data Layout

By default, Polaris stores data under the platform app-data directory unless POLARIS_ROOT is set.

Default paths:

• macOS: ~/Library/Application Support/polaris
• Linux: $XDG_DATA_HOME/polaris or ~/.local/share/polaris
• Windows: %APPDATA%\\polaris

Within that root, Polaris owns this layout:

<root>/
  data/
  tmp/
  cache/

• data/ stores snapshot files fetched from Polaris
• tmp/ stores temporary download state
• cache/ stores local cache state used by the CLI

Compatibility note:

• If the new default Polaris root does not exist but the legacy tick data root does, Polaris keeps using the legacy root automatically

Development

Useful local commands:

pnpm build:ts
pnpm check:ts
pnpm test:ts
node packages/cli/dist/cli/src/index.js --help