npm package: @opyne/cli
Description: CLI for the Opyne developer API — create questions, view results, and more
Latest version: 0.1.0

# @opyne/cli

Command-line interface for the Opyne developer API. List questions, view results, and create on-chain questions directly from your terminal.

## Install

```bash
npm install -g @opyne/cli
```

Or run without installing:

```bash
npx @opyne/cli list-questions
```

Requires Node.js 18+.

## Quick Start

```bash
# Configure defaults (optional — flags override these)
opyne config set --api-url https://opyne.co/v0 --keypair ~/.config/solana/id.json

# Browse questions
opyne list-questions
opyne list-questions --status active --limit 10
opyne get-question 42
opyne get-results 42 --bucket week

# Create a question (needs a funded Solana keypair with USDC)
opyne create-question \
  --topic "Best programming language?" \
  --options "Rust,TypeScript,Python,Go" \
  --amount 100 \
  --end-time "2026-06-01T00:00:00Z"
```

## Commands

### `opyne config set`

Persist default settings so you don't need to pass them every time.

```bash
opyne config set --api-url https://opyne.co/v0
opyne config set --keypair ~/.config/solana/id.json
```

Config is stored at `~/.config/opyne/config.json`.

### `opyne config show`

Print current configuration.

### `opyne list-questions`

List public, on-chain-confirmed questions.

| Flag | Description |
|------|-------------|
| `--status` | Filter: `active`, `completed`, or `upcoming` |
| `--limit` | Max results (default 20) |
| `--json` | Output raw JSON for scripting |
| `--api-url` | Override API base URL |

### `opyne get-question <id>`

Show details for a single question.

| Flag | Description |
|------|-------------|
| `--json` | Output raw JSON |
| `--api-url` | Override API base URL |

### `opyne get-results <id>`

Show vote counts, participation stats, and time-bucketed chart data.

| Flag | Description |
|------|-------------|
| `--bucket` | Time bucket: `day` (default), `week`, or `month` |
| `--json` | Output raw JSON |
| `--api-url` | Override API base URL |

### `opyne create-question`

Create an on-chain question. This is a two-step process: the CLI builds a transaction via the API, signs it locally with your keypair, then submits the signed transaction back to the API for on-chain confirmation.

| Flag | Description |
|------|-------------|
| `--topic` | Question text (required, max 200 chars) |
| `--options` | Comma-separated answer options (required, 2-10) |
| `--amount` | USDC to contribute (required) |
| `--start-time` | ISO 8601 start time (defaults to now) |
| `--end-time` | ISO 8601 end time (omit for perpetual) |
| `--cooldown` | Seconds between repeat votes (default 0 = one vote only) |
| `--demographic` | Demographic attributes as a JSON string (see below) |
| `--r-min` | Demographic tuning: minimum reward multiplier |
| `--r-max` | Demographic tuning: maximum reward multiplier |
| `--alpha` | Demographic tuning: alpha parameter |
| `--eta` | Demographic tuning: eta parameter |
| `--keypair` | Path to Solana keypair JSON file |
| `--api-url` | Override API base URL |

Your private key never leaves your machine — signing happens locally.

#### Demographic Config

Pass `--demographic` as a JSON array to require demographic balance. Each element specifies an attribute key and the allowed bucket indices:

```bash
opyne create-question \
  --topic "Best programming language?" \
  --options "Rust,TypeScript,Python" \
  --amount 100 \
  --demographic '[{"key":"gender","allowed_buckets":[0,1,2]},{"key":"ageGroup","allowed_buckets":[0,1,2,3,4,5]}]' \
  --r-min 0.5 --r-max 2.0 --alpha 1 --eta 0
```

Available attribute keys: `gender`, `country`, `region`, `postalBucket`, `ageGroup`, `race`, `politicalAffiliation`. Bucket indices correspond to the on-chain attestation values (see API docs for the full mapping).

## Debugging

Pass `--verbose` to any command to see debug output — resolved config, full API requests/responses, and transaction details:

```bash
opyne list-questions --verbose
opyne create-question --topic "Test" --options "A,B" --amount 10 --verbose
```

## Keypair Format

The CLI reads standard Solana keypair files (the JSON array format produced by `solana-keygen`):

```bash
solana-keygen new -o ~/.config/solana/id.json
```

## API

The CLI calls the Opyne v0 API at `/api/v0/`. Read endpoints are public (no auth). The `create-question` flow uses your wallet signature as authentication — the Solana program verifies the creator signer matches.

## Development

```bash
cd opyne/cli
npm install
npm run dev -- list-questions          # run from source via tsx
npm run build                          # bundle to dist/index.js via tsup
node dist/index.js list-questions      # run the built bundle
```