If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Polymarket/polymarket-cli shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 1w ago
• 2 active contributors
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 92% of recent commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Polymarket/polymarket-cli repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Polymarket/polymarket-cli.

What it runs against: a local clone of Polymarket/polymarket-cli — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Polymarket/polymarket-cli | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Polymarket/polymarket-cli. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Polymarket/polymarket-cli.git
#   cd polymarket-cli
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Polymarket/polymarket-cli and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Polymarket/polymarket-cli(\\.git)?\\b" \\
  && ok "origin remote is Polymarket/polymarket-cli" \\
  || miss "origin remote is not Polymarket/polymarket-cli (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/commands/mod.rs" \\
  && ok "src/commands/mod.rs" \\
  || miss "missing critical file: src/commands/mod.rs"
test -f "src/output/mod.rs" \\
  && ok "src/output/mod.rs" \\
  || miss "missing critical file: src/output/mod.rs"
test -f "src/config.rs" \\
  && ok "src/config.rs" \\
  || miss "missing critical file: src/config.rs"
test -f "src/auth.rs" \\
  && ok "src/auth.rs" \\
  || miss "missing critical file: src/auth.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Polymarket/polymarket-cli"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A Rust CLI for Polymarket (a prediction market platform) that lets users browse markets, place orders, manage positions, and interact with on-chain contracts without leaving the terminal. It wraps the polymarket-client-sdk and supports both human-readable table output and JSON for script/agent integration, with support for multiple wallet signature types (proxy, EOA, Gnosis Safe). Modular CLI structure: src/main.rs routes to command handlers in src/commands/ (approve.rs, clob.rs, wallet.rs, markets.rs, etc.), each with corresponding output formatters in src/output/. Config management in src/config.rs handles ~/.config/polymarket/config.json; src/auth.rs handles key management and signing. Built with clap for CLI parsing and polymarket-client-sdk for API calls.

Traders and market participants on Polymarket who want to browse prediction markets and execute trades from the command line; developers building trading bots or scripts that need JSON output; power users who prefer terminal workflows over web UIs.

Early-stage experimental software (v0.1.4). The README explicitly warns users to avoid large funds and expect API changes. CI/CD is configured (.github/workflows/ci.yml and release.yml exist), but test coverage appears minimal (only tests/cli_integration.rs visible). Not production-ready for high-value transactions.

High risk for financial operations: explicit warning in README against using with large funds, experimental status, minimal test suite, and dependency on polymarket-client-sdk (external). The wallet/signing logic (src/auth.rs, src/commands/approve.rs) handles private keys and signatures—any bugs here could leak funds. Single command binary means one vulnerability affects all operations.

No visible commit history in provided data, but the repository structure shows active command coverage (CLOB, CTF, bridge, sports, profiles, comments, tags modules). Release workflow is configured, suggesting regular version bumps. The experimental warning and v0.1.4 version suggest ongoing stabilization.

git clone https://github.com/Polymarket/polymarket-cli
cd polymarket-cli
cargo install --path .
# Or via Homebrew: brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli && brew install polymarket

Daily commands: After installation via cargo install --path ., run commands directly: polymarket markets list --limit 5 or polymarket setup for wallet initialization. No server to start—it's a pure CLI that makes HTTP/RPC calls to Polymarket and blockchain APIs. JSON output via polymarket -o json <command>.

• src/main.rs — Entry point for the CLI; defines argument parsing, command routing, and top-level error handling—every contributor must understand the command dispatch mechanism
• src/commands/mod.rs — Central module that imports and re-exports all command handlers; required to add any new command to the CLI
• src/output/mod.rs — Output formatting abstraction (JSON, table, etc.); all command results flow through this module before display
• src/config.rs — Configuration and authentication state management; handles wallet setup, API credentials, and persistent user settings
• src/auth.rs — Authentication logic for signing transactions and API requests; critical for secure interaction with Polymarket contracts
• Cargo.toml — Project manifest defining dependencies (polymarket-client-sdk, alloy, clap, tokio); version pinning and features directly impact runtime behavior
• src/commands/clob.rs — Core order book and trading logic; heaviest command module dealing with market data, order placement, and portfolio management

Add a New Command

1. Create a new file in src/commands/ (e.g., src/commands/newfeature.rs) with a public function matching the command signature (src/commands/newfeature.rs)
2. Define the clap subcommand struct with #[derive(Parser)] and clap attributes (src/commands/newfeature.rs)
3. Import and export the command in src/commands/mod.rs (e.g., pub mod newfeature;) (src/commands/mod.rs)
4. Add a handler in src/main.rs to match the new subcommand and call your command function (src/main.rs)
5. Create output formatting in src/output/newfeature.rs if returning structured data (src/output/newfeature.rs)

Add a New Output Format

1. Add a variant to the OutputFormat enum in src/output/mod.rs (e.g., XML, CSV, YAML) (src/output/mod.rs)
2. Implement a formatter function that takes the command result and returns formatted string (src/output/mod.rs)
3. Update the dispatch logic in src/output/mod.rs to call your formatter when that format is selected (src/output/mod.rs)

Add a New Market Data Query

1. Add a new subcommand variant in src/commands/markets.rs or src/commands/data.rs using clap derive macros (src/commands/markets.rs)
2. Call the polymarket-client-sdk API method corresponding to your query (src/commands/markets.rs)
3. Create or reuse an output struct in src/output/markets.rs to format the response (src/output/markets.rs)
4. Wire the output formatting in the command handler and return the formatted result (src/commands/markets.rs)

Add Wallet/Authentication Requirement

1. In your command handler (e.g., src/commands/clob.rs), call config::load() to load wallet credentials (src/commands/clob.rs)
2. Use auth::sign_transaction() or auth::get_api_key() to obtain signed payloads or credentials (src/auth.rs)
3. If wallet is not set up, return a helpful error message directing user to polymarket setup (src/commands/setup.rs)

• Rust + Cargo — Type-safe systems language with strong async support (tokio) for CLI performance and thread safety in key crypto operations
• polymarket-client-sdk — Official SDK abstracts Polymarket API and blockchain interactions (CLOB, CTF, data); reduces maintenance burden on CLI layer
• alloy (ethereum toolkit) — Handles low-level signing, contract encoding, and EVM interactions; critical for wallet operations and on-chain contract calls
• clap — Declarative argument parsing with derive macros reduces boilerplate and ensures consistent CLI UX across commands
• tokio runtime — Async I/O for concurrent SDK calls (market data + wallet state); non-blocking I/O essential for responsive terminal UX

• Single binary with embedded subcommands (markets, clob, data, etc.) vs. separate tools

  • Why: Unified CLI is easier for users (one install, one prefix polymarket) and simplifies shared config (wallet, auth)
  • Consequence: Binary size is larger; command namespace can become crowded; harder to maintain independent release cycles per feature

• Output formatters (JSON, table) in same binary vs. external post-processors

  • Why: JSON output is native and enables scripting without external tools; table rendering requires no dependencies from user
  • Consequence: CLI has more UI/formatting code; harder to change output format without recompiling

• Synchronous configuration file I/O (no async) in auth.rs and config.rs

  • Why: Configuration is typically loaded once at startup; synchronous I/O is simpler and avoids tokio runtime overhead for file ops
  • Consequence: Config changes during runtime are not supported; startup blocks on I/O (usually <10ms)

• Storing private keys in plaintext config file with file permissions (no encrypted vault)

  • Why: Simplicity for MVP; users control file permissions; explicit warning in README about risk
  • Consequence: High security risk if host is compromised; users must manually protect private key file

• Does not support real-time market streaming or subscriptions; all queries are one-shot REST calls
• Does not provide a graphical UI; terminal-only interface
• Does not implement a local order matching engine; all orders route to official Polymarket CLOB
• Does not cache market data across invocations (each command re-fetches from API)
• Does not support Windows natively (tested on macOS/Linux only; no official Windows binary)

Private key security: Private keys are stored unencrypted in ~/.config/polymarket/config.json—not suitable for high-value accounts. Network dependency: Commands require connectivity to Polymarket API and blockchain RPC (Polygon); timeouts not explicitly configured. Rust edition mismatch: Cargo.toml says edition = "2024" which is incorrect; should be "2021". Config file location: Hardcoded to ~/.config/ via dirs crate; no override flag visible. Wallet signature types: proxy mode requires Polymarket's backend; eoa and gnosis-safe are alternatives but may have different onchain implications. No key encryption: wallet create and wallet import don't encrypt the stored key.

• Proxy Wallet / Relayer Pattern — Polymarket's default signature_type=proxy uses a relayer to submit signed orders without requiring users to pay gas; understanding this vs EOA direct signing is critical for wallet setup.
• CLOB (Central Limit Order Book) — The core trading mechanism in Polymarket; src/commands/clob.rs and src/output/clob/ implement order placement, cancellation, and book querying.
• Conditional Token Framework (CTF) — Polymarket uses CTF for market mechanics; src/commands/ctf.rs implements split/merge/redeem operations that manage conditional token positions on-chain.
• EIP-191 Message Signing — Used by src/auth.rs for signing orders; understanding Ethereum's personal_sign vs raw signing is essential for wallet and signature logic.
• Gnosis Safe (Multisig Wallet) — One of three supported signature types (signature_type=gnosis-safe); users with multisig wallets need this flow, requiring different signing/transaction submission logic.
• Output Formatter Pattern (Polymorphism) — src/output/mod.rs defines a trait-based pattern where each command returns data that can be formatted as JSON or table; critical for extending output formats.
• Async Rust with Tokio — All API calls are async; src/commands/ modules use tokio::spawn and await for concurrent order/market queries.

• Polymarket/polymarket-client-sdk — The core SDK wrapped by this CLI; defines all API and on-chain interaction logic that the CLI delegates to.
• ethereum/go-ethereum — Underlying Ethereum/Polygon node client reference; alloy and wallet signing ultimately interact with EVM-compatible chains.
• foundry-rs/foundry — Rust-based Ethereum development toolkit; shares similar stack (alloy, signers) and wallet patterns for comparison.
• clap-rs/clap — The CLI argument parsing library used throughout; understanding clap's derive API is essential for adding new commands.
• Polymarket/clob-backend — Likely the backend API that polymarket-client-sdk calls; understanding CLOB order format/validation helps debug trading commands.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for all command modules (approve, bridge, clob, wallet, etc.)

The repo has only one integration test file (tests/cli_integration.rs) but 12+ command modules in src/commands/. Each command likely has distinct logic (approve.rs, bridge.rs, clob.rs, wallet.rs, etc.) that deserves specific test coverage. This would catch regressions and improve reliability for users.

• [ ] Expand tests/cli_integration.rs or create tests/commands/ subdirectory with test_*.rs files for approve, bridge, clob, wallet, ctf commands
• [ ] Add mock fixtures or recorded API responses for polymarket-client-sdk calls
• [ ] Test both success and error paths (invalid args, API failures, network timeouts)
• [ ] Run with cargo test in CI to validate each command's CLI parsing and output formatting

Add unit tests for src/auth.rs and src/config.rs core logic

Authentication and configuration are critical paths for CLI security and user setup. The auth.rs and config.rs modules have no visible test coverage despite handling wallet setup, key storage, and credential management. This is high-risk code that should have explicit tests.

• [ ] Create tests/auth_tests.rs with tests for credential loading, validation, and error cases
• [ ] Create tests/config_tests.rs to test config parsing, directory resolution (using dirs crate), and persistence
• [ ] Mock file I/O using tempdir or similar for isolation
• [ ] Test edge cases: missing config files, invalid JSON, file permission errors

Add GitHub Actions workflow for release artifact verification and binary signing

The .github/workflows/release.yml exists but there's no visible automation for verifying release artifacts or signing binaries. Given this is a financial trading tool, users need confidence in binary authenticity. The install.sh and Formula/polymarket.rb (Homebrew) both distribute binaries without checksums.

• [ ] Enhance .github/workflows/release.yml to generate SHA256 checksums for all release artifacts (Linux, macOS)
• [ ] Create a CHECKSUMS.txt file in release assets and include it in release notes
• [ ] Update install.sh to verify checksum after download (using sha256sum or shasum)
• [ ] Update Formula/polymarket.rb to include sha256 field pulled from release artifacts

• Add unit tests for src/config.rs (config loading/saving) and src/auth.rs (signature type resolution)—currently only integration tests exist in tests/cli_integration.rs
• Document the proxy vs EOA vs gnosis-safe signature type flow with code examples in README or a new docs/WALLET.md file; currently only brief mentions in config section
• Add polymarket wallet encrypt command to password-protect stored private keys in ~/.config/polymarket/config.json, since they're currently stored in plaintext

• High · Invalid Rust Edition — Cargo.toml. Cargo.toml specifies edition = '2024', which does not exist. Valid editions are 2015, 2018, and 2021. This will cause build failures and may indicate a configuration error or typo that could mask other issues. Fix: Change edition to a valid Rust edition, likely '2021' for a modern project targeting Rust 1.88.0
• Medium · Incomplete Dependency Pinning — Cargo.toml - dependencies section. Dependencies use semver ranges (e.g., 'polymarket-client-sdk' = '0.4', 'alloy' = '1.6.3') rather than exact versions. This allows automatic updates to compatible versions which may introduce breaking changes or security issues. The SDK dependency lacks a full version specification. Fix: Use exact version specifiers (=0.4.0) in production dependencies, especially for security-sensitive packages like cryptographic signers. Consider using a lock file and review updates carefully.
• Medium · Experimental Software Warning Not Enforced — src/main.rs, src/config.rs, src/commands/setup.rs. README warns users this is 'early, experimental software' and to 'not use with large amounts of funds', but there are no runtime warnings, safety checks, or version-pinning mechanisms in the code to prevent accidental use with real funds. Fix: Add startup warnings when connecting to mainnet. Implement explicit network selection with confirmation prompts for mainnet operations. Consider requiring explicit opt-in flags for fund-moving operations.
• Medium · Signer-Local Feature Enabled — Cargo.toml - alloy dependency features. The 'signer-local' feature is enabled in alloy dependency, which allows local private key signing. This increases risk if private keys are ever logged, cached in memory without proper cleanup, or exposed through error messages. Fix: Review all code paths handling private keys to ensure proper zeroing of sensitive data. Implement secure memory handling practices. Add checks to prevent accidental logging of keys or sensitive data.
• Medium · No Input Validation Framework Visible — src/commands/ - all command files. Using clap for CLI parsing but no evidence of sanitization library (e.g., input-validation crate). Commands like 'search' and filters could be vulnerable to injection if they construct queries or commands without proper escaping. Fix: Implement comprehensive input validation for all user-supplied parameters. Sanitize data before using it in API calls, contract interactions, or any external operations.
• Low · Shell Integration with eval Pattern — src/shell.rs. File 'src/shell.rs' suggests shell integration capabilities. Interactive shells that evaluate user input pose risks if not properly sandboxed or if they execute arbitrary commands. Fix: Review shell.rs for safe command execution patterns. Avoid using eval() or shell command construction from user input. Use parameterized/safe APIs for any shell operations.
• Low · Configuration File Directory Not Validated — src/config.rs. Code uses 'dirs' crate to find config directories but no evidence of validating config file permissions or ownership, which could allow privilege escalation if config contains sensitive data. Fix: Validate file permissions on loaded config files (should be readable only by owner on Unix). Warn users if config files have overly permissive permissions. Document secure setup procedures.
• Low · TLS Configuration Uses Default — Cargo.toml - alloy TLS dependency. The 'reqwest-rustls-tls' feature uses reasonable defaults, but no evidence of certificate pinning or custom validation for blockchain RPC endpoints which could be high-value targets. Fix: For critical blockchain endpoints, implement certificate pinning. Review and document TLS configuration choices. Consider validating RPC endpoints through signature verification.
• Low · No Audit Logging for Sensitive Operations — src/commands/approve.rs, src/commands/bridge.rs, src/commands/wallet.rs. No visible audit logging for operations involving fund transfers, approvals, or wallet operations. Makes it difficult to detect unauthorized access or debug security incidents. Fix:

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.