Command reference

All commands share a few conventions:

--json switches any command to raw, pipe-safe JSON on stdout.
--no-wait submits async work and prints the job_id instead of polling; resume with pulse jobs get.
--api-key overrides the stored credential for one invocation (also read from the PULSE_API_KEY environment variable).
-h after any command prints its full options.

pulse extract

Convert documents to markdown and JSON. Accepts any mix of file paths, directories (recursed for supported types), and URLs.

pulse extract report.pdf
pulse extract ./contracts -o ./results
pulse extract https://example.com/10k.pdf --pages "1-15" --chunking semantic

Each input produces <name>.pulse.md and <name>.pulse.json next to the source file (-o <dir> redirects; URL inputs land in the current directory). The output always includes the extraction_id you’ll need for follow-up commands. Add --schema to run extraction and structured output as one pipeline; the structured fields are written to <name>.pulse.schema.json:

pulse extract invoice.pdf --schema schemas/invoice.json
pulse extract invoice.pdf --schema '{"type":"object","properties":{"total":{"type":"number"}}}'

Flag	Description
`--schema <file or inline JSON>`	Extract, then apply this JSON Schema for structured output.
`--pages "1-2,5"`	Page range, 1-indexed.
`--model <name>`	Model override: `default` or `pulse-ultra-2`.
`--html`	Also return an HTML rendition.
`--footnotes`	Link footnote markers to their text.
`--figure-descriptions`	Caption figures and visuals.
`--show-images`	Return image URLs for visuals.
`--chunking semantic,page`	Chunk types: `semantic`, `header`, `page`, `recursive`.
`--chunk-size <n>`	Max characters per chunk.
`-o, --output <dir>`	Directory for result files.
`--no-wait`	Submit and print the `job_id` without polling.
`--json`	Print the full JSON result to stdout; write no files.

Files up to 50 MB upload directly. Pass larger documents by URL. See supported file types.

pulse schema

Structured extraction against a previous extraction. (To extract and structure in one command, use pulse extract --schema above.)

pulse schema generate

AI-draft a JSON Schema from a plain-English description, or refine an existing one:

pulse schema generate -p "vendor name, line items, total due" -o invoice.json
pulse schema generate --from invoice.json -p "also capture the PO number"

Flag	Description
`-p, --prompt <text>`	Describe the fields you want.
`--from <file>`	Existing schema JSON file to refine.
`-o, --output <file>`	Write the schema to a file (default: stdout).

pulse schema apply

Run a schema against extracted content:

pulse schema apply <extraction_id> --schema invoice.json
pulse schema apply --extraction-ids id1,id2 --schema combined.json
pulse schema apply --split-id <split_id> --split-schema-config per-topic.json

Flag	Description
`--schema <file>`	JSON Schema file.
`-p, --prompt <text>`	Extra extraction guidance (works with or without `--schema`).
`--extraction-ids a,b,c`	Combine several extractions.
`--split-id <id>`	Apply per-topic schemas to a split.
`--split-schema-config <file>`	Per-topic schema mapping (with `--split-id`).
`--schema-config-id <id>`	Use a schema config saved in the platform.
`--effort`	Higher-effort extraction.
`--pages "1-3"`	Restrict to a page range.
`-o, --output <file>`	Write result JSON to a file (default: stdout).

pulse split

Split a prior extraction into sections by topic:

pulse split <extraction_id> \
  -t "introduction:opening section" \
  -t "financials:tables and figures"

Flag	Description
`-t, --topic "name:description"`	Repeatable; description optional.
`--topics-file <json>`	JSON file: `[{name, description}, ...]`.
`--split-config-id <id>`	Use a split config saved in the platform.

Returns per-topic page ranges and content. The resulting split_id feeds pulse schema apply --split-id for per-topic structured extraction.

pulse tables

Pull tables out of a prior extraction:

pulse tables <extraction_id> --format html
pulse tables <extraction_id> -f json --merge --charts-to-tables

Flag	Description
`-f, --format html\|json`	Table output format (default: `html`).
`--merge`	Merge tables that span pages.
`--charts-to-tables`	Convert charts into tables too.
`-o, --output <file>`	Write result JSON to a file.

pulse jobs

Every long-running command runs async under the hood and polls for you. Hand control back with --no-wait, or press Ctrl-C while polling (the job keeps running server-side), and resume any time:

pulse jobs get <job_id>            # one-shot status (and result when complete)
pulse jobs get <job_id> --watch    # poll until the job is terminal
pulse jobs cancel <job_id>         # cancel a pending or processing job

pulse usage

Plan and usage for the current billing period: pages used vs. allowance, plus a breakdown by source (documents, pages, latency):

pulse usage
pulse usage --days 7
pulse usage --json

pulse open

Jump from the terminal to the platform:

pulse open <extraction_id>   # view an extraction
pulse open                   # open the dashboard

pulse login                       # browser device flow (default)
pulse login --api-key <key>       # log in with a key directly
pulse whoami                      # active key (redacted), engine URL, connectivity
pulse logout                      # remove the stored key

Credential precedence on every command:

--api-key <key> flag
PULSE_API_KEY environment variable (recommended for CI)
Stored credential from pulse login (OS keychain)

Treat your API key like a password. In CI, inject PULSE_API_KEY from your secret store rather than writing keys into scripts.

pulse login --base-url <url> points the CLI at a different engine (for example a VPC deployment).

Interactive mode

Bare pulse starts an interactive shell with the full command set and inline help.
pulse dashboard opens a full-screen account and usage view.

Scripting and output

Human-readable progress goes to the terminal; --json makes stdout pure JSON, so pulse extract report.pdf --json | jq .markdown just works.
File-writing commands echo every path they write plus the extraction_id.
Exit codes: 0 success, 1 failure (any document in a batch failing), 130 interrupted (job still running server-side).

# CI example: fail the step if extraction fails, keep the artifact
export PULSE_API_KEY="$PULSE_KEY_FROM_SECRETS"
pulse extract spec.pdf --json > spec.pulse.json

Troubleshooting

Authentication failed or 401

Run pulse whoami to see which credential is active and where it came from. A flag or PULSE_API_KEY overrides the stored key, so a stale environment variable is the usual culprit. Re-run pulse login to refresh the stored key.

The command returned a job_id but no result

You passed --no-wait or interrupted polling. The job is still running server-side: pulse jobs get <job_id> --watch picks it back up.

pulse usage errors but extraction works

pulse usage talks to the platform API rather than the extraction engine. Re-run pulse login (browser flow configures both), or set the platform URL with pulse login --platform-url https://platform.runpulse.com.

My file is over 50 MB

Direct uploads cap at 50 MB. Host the document somewhere reachable (a pre-signed S3 URL works) and pass the URL to pulse extract.

Payment required / out of credits

Your plan limit was reached. Check pulse usage, upgrade in the platform, or contact support.

pulse extract

pulse schema

pulse schema generate

pulse schema apply

pulse split

pulse tables

pulse jobs

pulse usage

pulse open

Interactive mode

Scripting and output

Troubleshooting

Next steps

CLI overview

API reference

​pulse extract

​pulse schema

​pulse schema generate

​pulse schema apply

​pulse split

​pulse tables

​pulse jobs

​pulse usage

​pulse open

​pulse login / whoami / logout

​Interactive mode

​Scripting and output

​Troubleshooting

​Next steps

CLI overview

API reference

pulse extract

pulse schema

pulse schema generate

pulse schema apply

pulse split

pulse tables

pulse jobs

pulse usage

pulse open

pulse login / whoami / logout

Interactive mode

Scripting and output

Troubleshooting

Next steps