npm package: @okrapdf/cli
Description: OkraPDF command-line interface for PDF extraction and document chat
Author: OkraPDF
Latest version: 0.5.3

# @okrapdf/cli

Command-line interface for [OkraPDF](https://okrapdf.com) - extract tables from PDFs.

## Installation

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

Or use with npx:

```bash
npx @okrapdf/cli jobs list
```

## Quick Start

```bash
# Create a .env file with your API key
echo "OKRA_API_KEY=okra_xxxxxxxxxxxx" > .env

# Or create ~/.okra for global config
echo "OKRA_API_KEY=okra_xxxxxxxxxxxx" > ~/.okra

# List your documents
okra docs list

# List extraction jobs  
okra jobs list

# Extract tables from a PDF
okra extract invoice.pdf -o json
```

Get your API key from [okrapdf.com/settings/api-keys](https://okrapdf.com/settings/api-keys).

## Configuration

The CLI looks for your API key in this order:

1. `OKRA_API_KEY` environment variable
2. `.env` file in current directory
3. `.okra` file in current directory
4. `~/.okra` file in home directory
5. `~/.config/okrapdf/config.json`

Example `.env` or `.okra` file:

```bash
OKRA_API_KEY=okra_xxxxxxxxxxxx
OKRA_BASE_URL=https://okrapdf.com
```

## Commands

### Documents

```bash
okra docs list               # List all documents
okra docs upload <file>      # Upload a PDF
okra docs get <uuid>         # Get document details
okra docs delete <uuid>      # Delete a document
```

### Jobs

```bash
okra jobs list               # List extraction jobs
okra jobs create <file>      # Create extraction job
okra jobs get <job-id>       # Get job status
okra jobs wait <job-id>      # Wait for completion
okra jobs results <job-id>   # Get extraction results
```

### Tables

```bash
okra tables list <doc-uuid>  # List extracted tables
okra tables get <table-id>   # Get table content
okra tables export <id>      # Export to CSV/JSON
```

### Shortcuts

```bash
okra extract <file>          # Upload + extract + wait (all-in-one)
```

### Interactive

```bash
okra chat <job-id>           # Interactive document chat
okra watch [job-ids...]      # Monitor live sessions in browser
```

### Introspection

```bash
okra schema [command ...]    # Machine-readable command schema
okra exit-codes              # Stable exit codes for automation
```

## Output Formats

All commands support `-o, --output`:

- `table` (default) - Human-readable tables
- `json` - Machine-readable JSON
- `csv` - CSV format

```bash
# JSON for scripting
okra jobs list -o json | jq '.[].id'

# Quiet mode for piping
okra extract doc.pdf -o json -q > results.json
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OKRA_API_KEY` | API key (required) |
| `OKRA_BASE_URL` | Custom API URL (for self-hosted) |
| `OKRA_OUTPUT_FORMAT` | Default output format |
| `OKRA_VERBOSE` | Enable verbose diagnostics when set to `1` |

## Examples

### Batch Processing

```bash
for pdf in *.pdf; do
  okra extract "$pdf" -o json > "${pdf%.pdf}.json"
done
```

### CI/CD Integration

```bash
# Extract and check for tables
RESULT=$(okra extract report.pdf -o json -q)
TABLE_COUNT=$(echo "$RESULT" | jq '.tables | length')
echo "Found $TABLE_COUNT tables"
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Authentication error |
| 4 | Resource not found |
| 5 | Rate limited |

## Development

```bash
git clone https://github.com/steventsao/okrapdf
cd okrapdf/packages/cli
npm install
npm run build
npm link
okra --help
```

## License

MIT

## Links

- [OkraPDF](https://okrapdf.com)
- [API Docs](https://docs.okrapdf.com/api)
- [GitHub](https://github.com/steventsao/okrapdf/tree/main/packages/cli)