allium-cli 0.2.0__tar.gz

allium_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen
+      - run: uv run pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

allium_cli-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "cli.prod.v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#cli.prod.v}"
+          PKG_VERSION="$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match pyproject.toml ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          PREV_TAG=$(git tag --sort=-creatordate | grep '^cli\.prod\.v' | sed -n '2p')
+          if [ -n "$PREV_TAG" ]; then
+            echo "range=$PREV_TAG...$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
+          else
+            echo "range=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: ""

allium_cli-0.2.0/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+env/
+venv/
+
+# Unit test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Type checkers
+.mypy_cache/
+.pytype/
+.pyre/
+
+# Ruff
+.ruff_cache/
+
+# Environments
+.env
+.envrc
+
+# PyPI
+.pypirc
+
+# OS
+.DS_Store
+Thumbs.db

allium_cli-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.4.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

allium_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+## Development setup
+
+```bash
+git clone https://github.com/Allium-Science/allium-cli.git
+cd allium-cli
+uv sync
+```
+
+Run the CLI locally:
+
+```bash
+uv run allium --help
+```
+
+### Tests
+
+```bash
+uv run pytest
+```
+
+### Linting
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## Release process
+
+Releases are automated via GitHub Actions, triggered by git tags.
+
+1. Bump `version` in `pyproject.toml` (e.g., `0.1.0` -> `0.2.0`)
+2. Commit and push to `main`
+3. Tag the release: `git tag cli.prod.v0.2.0 && git push origin cli.prod.v0.2.0`
+4. The tag triggers the publish workflow which builds and uploads to PyPI
+
+The workflow validates that the tag version matches `pyproject.toml` before publishing.

allium_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

allium_cli-0.2.0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: allium-cli
+Version: 0.2.0
+Summary: CLI for Allium blockchain data APIs
+Project-URL: Documentation, https://docs.allium.so
+Project-URL: Homepage, https://allium.so
+Project-URL: Repository, https://github.com/Allium-Science/allium-cli
+Author-email: Allium <support@allium.so>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Front-Ends
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: eth-account~=0.13
+Requires-Dist: httpx~=0.27
+Requires-Dist: privy-client~=0.5
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pympp[tempo]==0.3
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich-click>=1.9.7
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Description-Content-Type: text/markdown
+
+# Allium CLI
+
+Command-line interface for querying blockchain data across 80+ chains via the [Allium](https://allium.so) platform. Supports realtime token prices, wallet balances, transaction history, and SQL queries against Allium's data warehouse.
+
+## Installation
+
+```bash
+curl -sSL https://raw.githubusercontent.com/Allium-Science/allium-cli/main/install.sh | sh
+```
+
+Or install directly with your preferred package manager:
+
+```bash
+uv tool install allium-cli   # recommended
+pipx install allium-cli
+pip install allium-cli
+```
+
+This installs the `allium` command. Run `allium auth setup` to configure authentication.
+
+## Authentication
+
+The CLI supports four authentication methods. Run the interactive wizard, or pass arguments directly for scripted/CI setups:
+
+```bash
+# Interactive wizard (arrow-key selection)
+allium auth setup
+
+# Non-interactive one-liners
+allium auth setup --method api_key --api-key sk-...
+allium auth setup --method x402_key --private-key 0x... --network eip155:8453
+allium auth setup --method x402_privy \
+    --privy-app-id ... --privy-app-secret ... \
+    --privy-wallet-id ... --network eip155:8453
+allium auth setup --method tempo --private-key 0x... --chain-id 42431
+```
+
+| Method | Description |
+|---|---|
+| **API Key** | Standard key from [app.allium.so/settings/api-keys](https://app.allium.so/settings/api-keys) |
+| **x402 Private Key** | Pay-per-call with USDC on Base -- no API key needed |
+| **x402 Privy** | x402 via Privy server wallets -- no private key handling |
+| **Tempo MPP** | Tempo micropayment protocol |
+
+Optional flags: `--name <profile-name>` (defaults to the method name), `--no-active` (skip setting as active profile).
+
+Credentials are stored in `~/.config/allium/credentials.toml` (file permissions restricted to owner).
+
+### Profile management
+
+```bash
+allium auth list          # Show all profiles
+allium auth use <name>    # Switch active profile
+allium auth remove <name> # Delete a profile
+```
+
+## Global Options
+
+```
+--profile TEXT             Override the active auth profile for this command
+--format [json|table|csv]  Output format (default: json)
+-v, --verbose              Show progress details (run IDs, spinners, status)
+--help                     Show help and exit
+```
+
+## Commands
+
+### `allium realtime` -- Realtime Blockchain Data
+
+Query realtime blockchain data with 3-5s freshness across 20+ chains.
+
+#### Prices
+
+Token prices derived from on-chain DEX trades with VWAP calculation and outlier detection.
+
+```bash
+# Latest minute-level price and OHLC values
+allium realtime prices latest \
+  --chain solana --token-address So11111111111111111111111111111111111111112
+
+# Price at a specific timestamp
+allium realtime prices at-timestamp \
+  --chain ethereum --token-address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --timestamp 2026-01-15T12:00:00Z --time-granularity 1h
+
+# Historical price series
+allium realtime prices history \
+  --chain ethereum --token-address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
+  --start-timestamp 2026-01-01T00:00:00Z --end-timestamp 2026-01-07T00:00:00Z \
+  --time-granularity 1d
+
+# 24h/1h price stats (high, low, volume, trade count, percent change)
+allium realtime prices stats \
+  --chain solana --token-address So11111111111111111111111111111111111111112
+```
+
+**Options:** `--chain`, `--token-address` (repeatable, paired in order), `--body` (JSON override), `--timestamp`, `--start-timestamp`, `--end-timestamp`, `--time-granularity [15s|1m|5m|1h|1d]`
+
+#### Tokens
+
+```bash
+# List top tokens by volume
+allium realtime tokens list --chain ethereum --sort volume --limit 10
+
+# Fuzzy search by name or symbol
+allium realtime tokens search -q "USDC"
+
+# Exact lookup by chain + contract address
+allium realtime tokens chain-address \
+  --chain ethereum --token-address 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
+```
+
+**Options:** `--chain`, `--token-address` (repeatable), `--sort [volume|trade_count|fully_diluted_valuation|address|name]`, `--order [asc|desc]`, `--limit`, `-q/--query`
+
+#### Balances
+
+```bash
+# Current token balances for a wallet
+allium realtime balances latest \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+# Historical balance snapshots
+allium realtime balances history \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --start-timestamp 2026-01-01T00:00:00Z --limit 100
+```
+
+**Options:** `--chain`, `--address` (repeatable, paired), `--start-timestamp`, `--end-timestamp`, `--limit`, `--body`
+
+#### Transactions
+
+```bash
+# Wallet transaction activity with decoded activities and labels
+allium realtime transactions \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --activity-type dex_trade --lookback-days 7 --limit 50
+```
+
+**Options:** `--chain`, `--address` (repeatable), `--activity-type`, `--lookback-days`, `--limit`, `--body`
+
+#### PnL
+
+```bash
+# Wallet profit and loss
+allium realtime pnl \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+
+# With historical breakdown
+allium realtime pnl \
+  --chain ethereum --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 \
+  --with-historical-breakdown
+```
+
+**Options:** `--chain`, `--address` (repeatable), `--with-historical-breakdown`, `--body`
+
+---
+
+### `allium explorer` -- SQL Query Execution
+
+Run SQL queries on Allium's data warehouse. By default, the CLI polls silently and prints results. Use `-v` for progress details.
+
+```bash
+# Execute ad-hoc SQL (requires x402 or Tempo auth)
+allium explorer run-sql "SELECT chain, COUNT(*) FROM crosschain.dex.trades GROUP BY chain LIMIT 10"
+
+# Execute SQL from a file
+allium explorer run-sql query.sql --limit 1000
+
+# Run a saved query by ID with parameters
+allium explorer run abc123 --param start_date=2026-01-01 --param chain=ethereum
+
+# Just get the run ID without waiting
+allium explorer run-sql "SELECT 1" --no-wait
+
+# Check status of a query run
+allium explorer status <run_id>
+
+# Fetch results of a completed run
+allium explorer results <run_id>
+
+# Pipe CSV output directly
+allium --format csv explorer run-sql "SELECT 1" > output.csv
+```
+
+| Command | Description |
+|---|---|
+| `run-sql <SQL_OR_FILE>` | Execute ad-hoc SQL (x402/Tempo auth required) |
+| `run <QUERY_ID>` | Execute a saved Explorer query by ID |
+| `status <RUN_ID>` | Check query run status (created, running, success, failed, canceled) |
+| `results <RUN_ID>` | Download results of a completed run |
+
+**Options:** `--limit`, `--no-wait`, `--param key=value` (repeatable), `--compute-profile`
+
+---
+
+### `allium mp` -- Machine Payment Tracking
+
+Track costs for x402 and Tempo micropayment API calls. Payments are logged automatically to `~/.config/allium/cost_log.csv`.
+
+```bash
+# Total spend summary grouped by method and network
+allium mp cost
+
+# Full itemized payment history
+allium mp cost list
+
+# Export as CSV
+allium --format csv mp cost list
+
+# Clear the cost log
+allium mp cost clear
+```
+
+| Command | Description |
+|---|---|
+| `mp cost` | Total spend summary (grouped by method/network with call counts) |
+| `mp cost list` | Full itemized history with per-row details |
+| `mp cost clear` | Delete the cost log (with confirmation prompt) |
+
+---
+
+### `allium auth` -- Authentication Management
+
+```bash
+# Interactive setup wizard (arrow-key selection)
+allium auth setup
+
+# Non-interactive setup (for scripts/CI)
+allium auth setup --method api_key --api-key sk-...
+allium auth setup --method tempo --private-key 0x... --chain-id 42431
+
+# List all configured profiles
+allium auth list
+
+# Switch active profile
+allium auth use <name>
+
+# Delete a profile
+allium auth remove <name>
+```
+
+## JSON Body Override
+
+All realtime commands support a `--body` flag that accepts either inline JSON or a path to a `.json` file. When provided, it overrides all other options:
+
+```bash
+# Inline JSON
+allium realtime prices latest --body '[{"chain":"solana","token_address":"So111..."}]'
+
+# From file
+allium realtime prices latest --body tokens.json
+```
+
+## Shell Completions
+
+Tab-completion is available for all commands, subcommands, and options. Add one of the following to your shell config:
+
+```bash
+# Bash — add to ~/.bashrc
+eval "$(_ALLIUM_COMPLETE=bash_source allium)"
+
+# Zsh — add to ~/.zshrc
+eval "$(_ALLIUM_COMPLETE=zsh_source allium)"
+
+# Fish — add to ~/.config/fish/config.fish
+_ALLIUM_COMPLETE=fish_source allium | source
+```
+
+Reload your shell to activate completions.
+
+## Documentation
+
+Full API documentation: [docs.allium.so](https://docs.allium.so)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and release instructions.