# Go CLI
URL: https://backworkhealth.com/docs/sdks/go

Command-line tool for Backwork with single binary distribution

The Backwork CLI is a powerful command-line tool for interacting with the Backwork API. Perfect for DevOps workflows, automation scripts, and quick lookups from the terminal.

**Production availability of the endpoints on this page**

| Operation                                                | Endpoint                               | Production |
| -------------------------------------------------------- | -------------------------------------- | ---------- |
| [`checkPriorAuth`](/docs/api/checkPriorAuth)             | `POST /api/v1/prior-auth/check`        | Live       |
| [`lookupCode`](/docs/api/lookupCode)                     | `GET /api/v1/codes/lookup`             | Live       |
| [`listPolicies`](/docs/api/listPolicies)                 | `GET /api/v1/policies`                 | Live       |
| [`getPolicy`](/docs/api/getPolicy)                       | `GET /api/v1/policies/{id}`            | Live       |
| [`getPolicyChanges`](/docs/api/getPolicyChanges)         | `GET /api/v1/policies/changes`         | Live       |
| [`comparePolicies`](/docs/api/comparePolicies)           | `POST /api/v1/policies/compare`        | Live       |
| [`listJurisdictions`](/docs/api/listJurisdictions)       | `GET /api/v1/jurisdictions`            | Live       |
| [`searchCriteria`](/docs/api/searchCriteria)             | `GET /api/v1/coverage/criteria`        | Live       |
| [`researchPriorAuth`](/docs/api/researchPriorAuth)       | `POST /api/v1/prior-auth/research`     | Live       |
| [`getPriorAuthResearch`](/docs/api/getPriorAuthResearch) | `GET /api/v1/prior-auth/research/{id}` | Live       |
| [`getSpendingByCode`](/docs/api/getSpendingByCode)       | `GET /api/v1/spending/by-code`         | Live       |

## Installation [#installation]

### Install from Source [#install-from-source]

```bash
git clone https://github.com/tylergibbs1/backwork-cli.git
cd backwork-cli
go mod tidy
go build -o backwork .
sudo mv backwork /usr/local/bin/
```

### Go Install [#go-install]

```bash
go install github.com/tylergibbs1/backwork-cli/cmd/backwork@v1.1.0
```

### Download Binary [#download-binary]

Pre-built binaries and checksums are available from [GitHub Releases](https://github.com/tylergibbs1/backwork-cli/releases).

## Quick Start [#quick-start]

Set your API key as an environment variable:

```bash
export BACKWORK_API_KEY=bwk_live_YOUR_API_KEY
```

The CLI reads `BACKWORK_API_KEY`.

Or pass it with each command:

```bash
backwork --api-key bwk_live_YOUR_API_KEY check 76942
```

Get your API key from the [API usage and keys](https://backworkhealth.com/api-usage).

## Common Use Cases [#common-use-cases]

### Check if a Procedure Needs Prior Authorization [#check-if-a-procedure-needs-prior-authorization]

```bash
# Basic prior auth check
backwork prior-auth 27447 --state TX

# With diagnosis codes
backwork prior-auth 27447 --diagnosis M17.11 --state TX

# Multiple procedure codes
backwork prior-auth 27447 76942 --state CA

# JSON output for scripting
backwork prior-auth 27447 --state TX --output json | jq '.data.pa_required'
```

**Output:**

```
Prior Authorization Required: true
Confidence: high
Reason: Procedure requires prior authorization in Texas

Matched Policies:
  • L33831: Ultrasound Guidance for Needle Placement
  • L38942: Diagnostic Ultrasound

Documentation Checklist:
  • Medical necessity documentation
  • Prior imaging results
  • Conservative treatment history
```

### Look Up Procedure Code with Coverage Info [#look-up-procedure-code-with-coverage-info]

```bash
# Basic code lookup
backwork check 76942

# With RVU reimbursement data
backwork check 76942 --rvu

# With coverage policies
backwork check 76942 --policies

# Everything (RVU + policies)
backwork check 76942 --rvu --policies

# Filter by jurisdiction
backwork check 76942 --jurisdiction JM
```

**Output:**

```
Code: 76942
System: HCPCS
Found: true
Description: Echo guide for biopsy

RVU Data (2026):
  Work RVU: 0.65
  Facility Price: $64.13
  Non-Facility Price: $64.13

Coverage Policies (16 found):
  • [covered] Billing and Coding: Varicose Veins
  • [covered] Billing and Coding: Nerve Blockade
  • [not_covered] Ultrasound Guidance for Trigger Point Injections
```

### Search Coverage Policies [#search-coverage-policies]

```bash
# Keyword search
backwork policies list --query "ultrasound guidance"

# Filter by policy type
backwork policies list --query "diabetes" --type LCD

# Filter by jurisdiction
backwork policies list --query "CGM" --jurisdiction JM

# Active policies only
backwork policies list --query "surgery" --status active

# JSON output
backwork policies list --query "ultrasound" --output json | jq '.data[].policy_id'
```

**Output:**

```
Found 50 policies:

ID: A57305
Title: Billing and Coding: Varicose Veins of the Lower Extremity
Type: Article
Jurisdiction: JM
Status: active
---
ID: L33831
Title: Ultrasound Guidance for Needle Placement
Type: LCD
Jurisdiction: J06
Status: active
---
```

### Get Detailed Policy Information [#get-detailed-policy-information]

```bash
# Get policy by ID
backwork policies get L33831

# JSON output for parsing
backwork policies get L33831 --output json | jq '.data.title'
```

**Output:**

```
Policy: L33831
Title: Ultrasound Guidance for Needle Placement
Type: LCD
Status: active
Jurisdiction: J06
Effective Date: 2024-01-01

Description:
This LCD outlines coverage requirements for ultrasound guidance
used during needle placement procedures...

Covered Codes (12):
  • 76942 (HCPCS): covered
  • 76998 (HCPCS): covered
```

### List MAC Jurisdictions [#list-mac-jurisdictions]

```bash
# List all jurisdictions
backwork jurisdictions

# JSON output
backwork jurisdictions --output json
```

**Output:**

```
Medicare Administrative Contractors (MACs):

JM: Palmetto GBA
  States: TX, OK, NM, CO, LA, AR, MS

J05: Novitas Solutions
  States: PA, NJ, DE, MD, DC, WV

J06: National Government Services
  States: IL, MN, WI
```

### Research Prior Auth with AI Web Search [#research-prior-auth-with-ai-web-search]

```bash
# Async mode - returns research ID for polling
backwork prior-auth research 27447 --payer "UnitedHealthcare" --state TX

# Output:
# Research ID: res_abc123
# Status: pending
# Poll URL: /api/v1/prior-auth/research/res_abc123
#
# Use 'backwork prior-auth research-status <research-id>' to check progress

# Check research status
backwork prior-auth research-status res_abc123

# Sync mode - waits for completion
backwork prior-auth research 27447 --payer "Aetna" --state CA --sync

# JSON output
backwork prior-auth research 27447 --payer "UnitedHealthcare" --sync --output json | jq '.data.result.determination'
```

### Get Medicaid Spending Data [#get-medicaid-spending-data]

```bash
# Single code
backwork spending T1019

# Multiple codes
backwork spending T1019 T1020

# Filter by year
backwork spending T1019 --year 2023

# JSON output for scripting
backwork spending T1019 --output json | jq '.data.T1019.total_paid'
```

### Check API Health [#check-api-health]

```bash
backwork health

# Output:
# Status: healthy
# Version: 1.0.0
# Timestamp: 2026-02-17T12:00:00Z
#
# Checks:
#   database: healthy
#   redis: healthy
```

### Search Coverage Criteria [#search-coverage-criteria]

```bash
# Search criteria text
backwork coverage search "BMI greater than 40"

# Filter by section and policy type
backwork coverage search "conservative treatment" --section indications --type LCD

# Filter by jurisdiction
backwork coverage search "frequency limits" --jurisdiction JM

# JSON output
backwork coverage search "BMI" --output json | jq '.data[].text'
```

### Compare Policies Across Jurisdictions [#compare-policies-across-jurisdictions]

```bash
# Compare coverage for a procedure
backwork policies compare 76942

# Compare specific jurisdictions
backwork policies compare 76942 --jurisdictions J05,J06,JM

# Multiple codes with policy type filter
backwork policies compare 27447 76942 --type LCD

# JSON output
backwork policies compare 76942 --output json | jq '.data.comparison'
```

## Scripting & Automation [#scripting--automation]

### Check Multiple Codes in a Loop [#check-multiple-codes-in-a-loop]

```bash
#!/bin/bash

CODES=("76942" "27447" "99213" "J0585")

for code in "${CODES[@]}"; do
  echo "Checking $code..."
  backwork check "$code" --output json | jq -r '.data.description'
done
```

### Monitor for Policy Changes [#monitor-for-policy-changes]

```bash
#!/bin/bash

# Get changes from the last 24 hours
SINCE=$(date -u -v-24H +"%Y-%m-%dT%H:%M:%SZ")  # macOS
# SINCE=$(date -u -d '24 hours ago' +"%Y-%m-%dT%H:%M:%SZ")  # Linux

backwork policies changes --since "$SINCE" --output json | \
  jq -r '.data[] | "\(.policy_id): \(.change_type) - \(.change_summary)"'
```

### Pre-submission Prior Auth Check [#pre-submission-prior-auth-check]

```bash
#!/bin/bash

# Check if procedures need PA before submitting claim
PROCEDURES=("27447" "76942")
DIAGNOSES=("M17.11" "M79.3")
STATE="TX"

result=$(backwork prior-auth "${PROCEDURES[@]}" \
  --diagnosis "${DIAGNOSES[@]}" \
  --state "$STATE" \
  --output json)

pa_required=$(echo "$result" | jq -r '.data.pa_required')

if [ "$pa_required" = "true" ]; then
  echo "Warning: Prior authorization required!"
  echo "$result" | jq -r '.data.documentation_checklist[]'
  exit 1
else
  echo "No prior authorization needed"
  exit 0
fi
```

### Export Policy Data to CSV [#export-policy-data-to-csv]

```bash
#!/bin/bash

# Search and export to CSV
backwork policies list --query "diabetes" --output json | \
  jq -r '.data[] | [.policy_id, .title, .policy_type, .status] | @csv' > policies.csv
```

## Output Formats [#output-formats]

The CLI supports multiple output formats:

```bash
# Table (default) - human-readable
backwork check 76942

# JSON - for scripting
backwork check 76942 --output json

# YAML - for configuration
backwork check 76942 --output yaml
```

## Configuration File [#configuration-file]

Save your API key and preferences in a config file:

```bash
# Create config file
mkdir -p ~/.backwork
cat > ~/.backwork/config.yaml << EOF
api-key: bwk_live_YOUR_API_KEY
base-url: https://backworkhealth.com/api/v1
output: table
EOF

# Now you can use the CLI without --api-key
backwork check 76942
```

## Global Flags [#global-flags]

Available for all commands:

```bash
--api-key string    # Backwork API key (or set BACKWORK_API_KEY env var)
--base-url string   # API base URL (default: https://backworkhealth.com/api/v1)
--output string     # Output format: table, json, yaml (default: table)
--config string     # Config file (default: $HOME/.backwork/config.yaml)
```

## All Commands [#all-commands]

### `backwork check <code>` [#backwork-check-code]

Look up a medical code.

**Flags:**

* `--jurisdiction <code>` - Filter by MAC jurisdiction
* `--rvu` - Include RVU data
* `--policies` - Include policy information

**Example:**

```bash
backwork check 76942 --rvu --policies --jurisdiction JM
```

### `backwork health` [#backwork-health]

Check API health status.

**Example:**

```bash
backwork health
```

### `backwork prior-auth <codes...>` [#backwork-prior-auth-codes]

Check prior authorization requirements.

**Flags:**

* `--diagnosis <codes>` - Diagnosis codes (ICD-10)
* `--state <state>` - Two-letter state code
* `--payer <payer>` - Payer (medicare, aetna, uhc, all)

**Example:**

```bash
backwork prior-auth 27447 76942 --diagnosis M17.11 --state TX
```

### `backwork prior-auth research <codes...>` [#backwork-prior-auth-research-codes]

Research prior auth requirements via AI web search.

**Flags:**

* `--payer <name>` - Payer name (e.g., UnitedHealthcare, Aetna)
* `--state <state>` - Two-letter state code
* `--diagnosis <codes>` - Diagnosis codes (ICD-10)
* `--context <text>` - Additional clinical context
* `--sync` - Wait for completion

**Example:**

```bash
backwork prior-auth research 27447 --payer "UnitedHealthcare" --state TX --sync
```

### `backwork prior-auth research-status <research-id>` [#backwork-prior-auth-research-status-research-id]

Poll the status of a prior auth research task.

**Example:**

```bash
backwork prior-auth research-status res_abc123
```

### `backwork policies list` [#backwork-policies-list]

Search and list policies.

**Flags:**

* `--query <query>` - Search query
* `--type <type>` - Policy type (LCD, Article, NCD)
* `--jurisdiction <code>` - MAC jurisdiction
* `--status <status>` - Status (active, retired, all)
* `--mode <mode>` - Search mode (keyword, semantic)

**Example:**

```bash
backwork policies list --query "ultrasound" --type LCD --status active
```

### `backwork policies get <policy-id>` [#backwork-policies-get-policy-id]

Get detailed policy information.

**Example:**

```bash
backwork policies get L33831
```

### `backwork policies changes` [#backwork-policies-changes]

Get policy change feed.

**Flags:**

* `--since <timestamp>` - ISO 8601 timestamp
* `--policy-id <id>` - Filter by policy ID
* `--change-type <type>` - Change type filter

**Example:**

```bash
backwork policies changes --since 2026-01-01T00:00:00Z
```

### `backwork policies compare <codes...>` [#backwork-policies-compare-codes]

Compare policies across jurisdictions.

**Flags:**

* `--type <type>` - Policy type (LCD, Article, NCD)
* `--jurisdictions <codes>` - Specific jurisdictions to compare

**Example:**

```bash
backwork policies compare 76942 --jurisdictions J05,J06,JM
```

### `backwork jurisdictions` [#backwork-jurisdictions]

List all MAC jurisdictions.

**Example:**

```bash
backwork jurisdictions
```

### `backwork coverage search <query>` [#backwork-coverage-search-query]

Search coverage criteria text across policies.

**Flags:**

* `--section <section>` - Filter by section (indications, limitations, documentation)
* `--type <type>` - Policy type (LCD, Article, NCD)
* `--jurisdiction <code>` - MAC jurisdiction
* `--limit <n>` - Results per page (1-100)

**Example:**

```bash
backwork coverage search "BMI greater than 40" --section indications --type LCD
```

### `backwork spending <codes...>` [#backwork-spending-codes]

Get Medicaid spending data by HCPCS code.

**Flags:**

* `--year <year>` - Filter to a specific year

**Example:**

```bash
backwork spending T1019 T1020 --year 2023
```

## Shell Completion [#shell-completion]

Generate shell completion scripts:

```bash
# Bash
backwork completion bash > /usr/local/etc/bash_completion.d/backwork

# Zsh
backwork completion zsh > /usr/local/share/zsh/site-functions/_backwork

# Fish
backwork completion fish > ~/.config/fish/completions/backwork.fish

# PowerShell
backwork completion powershell | Out-String | Invoke-Expression
```

## Building from Source [#building-from-source]

```bash
git clone https://github.com/tylergibbs1/backwork-cli.git
cd backwork-cli
go mod tidy
go build -o backwork .
./backwork --help
```

**Build for all platforms:**

```bash
make build-all
# Creates binaries in dist/ for:
# - darwin/amd64, darwin/arm64
# - linux/amd64, linux/arm64
# - windows/amd64
```

## Resources [#resources]

* **GitHub**: [backworkhealth/backwork-cli](https://github.com/tylergibbs1/backwork-cli)
* **Releases**: [Download Binaries](https://github.com/tylergibbs1/backwork-cli/releases)
* **API Reference**: [All Endpoints](/docs/api)
* **Issues**: [Report a bug](https://github.com/tylergibbs1/backwork-cli/issues)

## Next Steps [#next-steps]

<Cards>
  <Card title="API Reference" href="/docs/api" description="Explore all available endpoints" />

  <Card title="Authentication" href="/docs/authentication" description="Learn about API keys" />

  <Card title="Automation Guide" href="/docs/automation" description="Build workflows with the CLI" />
</Cards>