docs: make polymarket-cli the only public command

Author: ra1nty

README.md

@@ -2,179 +2,68 @@
 
 Read-only CLI for public Polymarket Gamma, CLOB, and Data API lookups.
 
-This repo stays intentionally narrow: public, unauthenticated reads only. It does not place orders, manage wallets, sign anything, or depend on private APIs.
+This package stays intentionally narrow: public, unauthenticated reads only. It does not place orders, manage wallets, sign anything, or depend on private APIs.
 
-The published Python distribution is `polymarket-cli`, the import package is `polymarket_cli`, and the command stays `pmkt`.
+The published Python distribution is `polymarket-cli`, the import package is `polymarket_cli`, and the command is `polymarket-cli`.
 
-## What `pmkt` covers
+## What It Covers
 
-- market discovery via `search` and `list`
-- market detail lookup via `market`
-- order book and spot pricing via `book`, `midpoint`, and `price`
-- recent public trades via `trades`
-- public token price history via `history`
-
-The CLI uses only public Polymarket endpoints:
-
-- Gamma `GET /markets`
-- Gamma `GET /markets/{id}` and `GET /markets/slug/{slug}`
-- Gamma `GET /public-search`
-- CLOB `GET /book`
-- CLOB `GET /midpoint`
-- CLOB `GET /last-trade-price`
-- CLOB `GET /prices-history`
-- Data API `GET /trades`
+- Market discovery via `search` and `list`
+- Market detail lookup via `market`
+- Order book and spot pricing via `book`, `midpoint`, and `price`
+- Recent public trades via `trades`
+- Public token price history via `history`
 
 ## Install
 
-### Default for a local checkout
-
-Use `uv tool install --editable .` for the real `pmkt` entrypoint while keeping the checkout live:
-
 ```bash
-uv tool install --editable .
-pmkt --help
+uv tool install polymarket-cli
+polymarket-cli --help
 ```
 
-If uv's tool bin directory is not on your `PATH` yet:
+For one-off execution:
 
 ```bash
-uv tool update-shell
-# or run the binary directly
-"$(uv tool dir --bin)"/pmkt --help
+uvx polymarket-cli --help
 ```
 
-For one-off execution without installing:
+If your `uv` tool bin directory is not on `PATH`, either run `uv tool update-shell` or call the binary directly from `$(uv tool dir --bin)`.
 
-```bash
-uvx --from . pmkt --help
-```
+## Claude Code And Codex
 
-### Default for a published release
+In Claude Code or Codex, install the published CLI in the agent shell environment:
 
 ```bash
 uv tool install polymarket-cli
-pmkt --help
+polymarket-cli search bitcoin --limit 5
 ```
 
-### Secondary project-mode execution
+For ephemeral runs inside those environments:
 
 ```bash
-uv run pmkt --help
+uvx polymarket-cli market --slug <market-slug> --json
 ```
 
-## Usage
+If you want the agent to treat this repo as a reusable skill bundle, use the bundled skill at `skills/polymarket-cli/`.
 
-### Market discovery
+## Usage
 
 ```bash
-pmkt search bitcoin --limit 5
-pmkt search election --sort liquidity --json
-pmkt search iran --sort volume24hr --active-only --with-odds --limit 5
-
-pmkt list --active-only --sort volume24hr --limit 20
-pmkt list --closed-only --sort endDate --ascending --limit 20
-pmkt list --tag-id 100381 --related-tags --limit 25
-pmkt list --min-liquidity 10000 --min-volume24hr 5000
+polymarket-cli search bitcoin --limit 5
+polymarket-cli list --active-only --sort volume24hr --limit 20
+polymarket-cli market --slug btc-updown-5m-1774165800
+polymarket-cli book --slug btc-updown-5m-1774165800 --outcome Down
+polymarket-cli price --slug btc-updown-5m-1774165800
+polymarket-cli history --slug btc-updown-5m-1774165800 --window 6h --format summary --json
+polymarket-cli trades --slug btc-updown-5m-1774165800 --limit 20
 ```
 
-Useful options:
+Useful flags:
 
 - `--json` is available on every command.
 - `--hydrate` resolves search/list rows to full market detail before local ranking or filtering.
 - `--with-odds` implies hydration and includes current outcome prices.
 - `--with-market` implies hydration and embeds the resolved market payload in JSON output.
-- Supported sort values are `volume24hr`, `volume`, `liquidity`, `startDate`, `endDate`, `competitive`, and `closedTime`.
-
-### Market details
-
-```bash
-pmkt market --slug btc-updown-5m-1774165800
-pmkt market --id 1669969 --json
-```
-
-### Order book and spot pricing
-
-```bash
-pmkt book --token-id 94242206871221370391055736153305071391564432448684801902267396130896523340261
-pmkt midpoint --token-id 94242206871221370391055736153305071391564432448684801902267396130896523340261
-pmkt price --slug btc-updown-5m-1774165800
-pmkt book --slug btc-updown-5m-1774165800 --outcome Down
-```
-
-### Price history
-
-```bash
-pmkt history --token-id 94242206871221370391055736153305071391564432448684801902267396130896523340261 \
-  --interval 1h \
-  --fidelity 5 \
-  --start 2026-03-22T00:00:00Z \
-  --end 2026-03-22T12:00:00Z
-
-pmkt history --slug btc-updown-5m-1774165800 --outcome Down --interval 1h --window 60 --format ohlc
-pmkt history --slug btc-updown-5m-1774165800 --window 6h --format summary --json
-```
-
-Supported history intervals:
-
-- `max`
-- `all`
-- `1m`
-- `1h`
-- `6h`
-- `1d`
-- `1w`
-
-### Public trades
-
-```bash
-pmkt trades --slug btc-updown-5m-1774165800 --limit 20
-pmkt trades --condition-id 0xba3509c3c29a52bb2f8cf8204755314a38461825e61e77e6350f5abd4b848e05 --json
-```
-
-## CLI behavior
-
-- Text output is line-oriented by default.
-- `--json` is available everywhere for automation.
 - Market selectors are explicit: `--slug`, `--id`, `--token-id`, `--condition-id`.
-- If no `--outcome` is given for token-resolving commands, the first market token is used.
-- Ranked search/list JSON includes ranking metadata so downstream tools can detect fallback or degraded result sets.
-
-## Development
-
-Run tests:
-
-```bash
-uv run --no-project python -m unittest discover -s tests -v
-```
-
-Build artifacts:
-
-```bash
-uv build
-```
-
-Quick smoke checks:
-
-```bash
-uvx --from . pmkt --help
-uvx --from . pmkt search --help
-```
-
-The fixture-backed test suite does not require live network access.
-
-## Release publishing
-
-GitHub Actions handles publishing to TestPyPI and PyPI with trusted publishing (OIDC). No API tokens or repository secrets are required in this repo.
-
-Required GitHub-side setup:
-
-1. Configure a trusted publisher for this repository in TestPyPI.
-2. Configure a trusted publisher for this repository in PyPI.
-3. If you want manual approval before production release, protect the GitHub `pypi` environment.
-
-Workflow behavior:
 
-- CI runs on pushes and pull requests.
-- TestPyPI publishing runs on version tags like `v1.2.3-rc1` and by manual dispatch.
-- PyPI publishing runs on GitHub release publication and by manual dispatch.
+Supported history intervals: `max`, `all`, `1m`, `1h`, `6h`, `1d`, `1w`.

polymarket_cli/cli.py

@@ -185,7 +185,7 @@ def _resolve_market_filters(args: argparse.Namespace) -> dict[str, Any]:
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        prog="pmkt",
+        prog="polymarket-cli",
         description="Read-only Polymarket Gamma + CLOB CLI for market discovery, price snapshots, trades, and history",
     )
     sub = parser.add_subparsers(dest="command", required=True)

pyproject.toml

@@ -13,7 +13,7 @@ license = { text = "MIT" }
 dependencies = []
 
 [project.scripts]
-pmkt = "polymarket_cli.cli:main"
+polymarket-cli = "polymarket_cli.cli:main"
 
 [tool.uv.build-backend]
 module-name = "polymarket_cli"

skills/pmkt/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: polymarket-cli
+description: Use the polymarket-cli command for read-only Polymarket market discovery, market/token resolution, price snapshots, history, trades, and JSON-safe scripting.
+---
+
+# Using `polymarket-cli`
+
+Use this skill when an agent needs public, read-only Polymarket data from this package without calling Gamma, CLOB, or Data API endpoints directly.
+
+Install the published CLI:
+
+```bash
+uv tool install polymarket-cli
+polymarket-cli --help
+```
+
+For one-off execution without installing:
+
+```bash
+uvx polymarket-cli --help
+```
+
+## When to use `polymarket-cli`
+
+- Discover markets by keyword, liquidity, volume, tags, or date windows.
+- Resolve a market `slug` or `id` into a `conditionId` or outcome `token_id`.
+- Pull spot pricing with `book`, `midpoint`, or `price`.
+- Pull recent public trades for a market condition.
+- Pull token price history and locally aggregate it into OHLC or summaries.
+- Produce scriptable JSON output for another tool or agent step.
+
+## Command patterns
+
+```bash
+polymarket-cli search bitcoin --limit 5
+polymarket-cli list --active-only --sort liquidity --min-liquidity 10000
+polymarket-cli market --slug <market-slug> --json
+polymarket-cli book --slug <market-slug> --outcome Yes
+polymarket-cli history --slug <market-slug> --window 6h --format summary --json
+polymarket-cli trades --condition-id <condition-id> --json
+```
+
+## Working rules
+
+- Prefer `polymarket-cli` in docs, prompts, and automation.
+- Prefer `--json` whenever another step will parse the result.
+- Use explicit selectors: `--slug`, `--id`, `--token-id`, `--condition-id`.
+- Keep usage read-only. This package does not place orders, manage wallets, or use private/authenticated APIs.

skills/polymarket-cli/SKILL.md

@@ -111,6 +111,12 @@ def test_search_uses_search_markets_for_query(self):
             ),
         )
 
+    def test_parser_uses_public_command_name(self):
+        parser = cli.build_parser()
+
+        self.assertEqual(parser.prog, "polymarket-cli")
+        self.assertIn("usage: polymarket-cli", parser.format_help())
+
     def test_list_passes_advanced_filtering_flags(self):
         rc, output, client = self.run_cli(
             [