Docufin CLI

The Docufin CLI lets you scaffold, validate, compile, and deploy pipelines from your local workspace. It is built for deterministic artifacts and CI-friendly output so you can ship workflows with confidence.

Requirements

• Bun 1.3 or later installed locally
• A Docufin project id and API token when deploying

Running the CLI

The CLI is invoked as npx @docufin/cli. From a source checkout you can run it with Bun (for example bun run packages/@docufin/cli/src/index.tsx --help) until the packaged build is published. All commands share a consistent shape:

npx @docufin/cli [global options] <command> [command options]

Global options

• --project <id>: Docufin project id (env: DOCUFIN_PROJECT)
• --token <token>: API token (env: DOCUFIN_TOKEN)
• --api <url>: API base URL (env: DOCUFIN_API, defaults to compiled value)
• --json: emit a single JSON object to stdout (success or error)
• --quiet: suppress non-essential logs (errors still go to stderr)
• --cwd <path>: run as if invoked from another directory

Precedence: flags override environment variables, which override any workspace config file (workspace config lands after the MVP).

Commands

npx @docufin/cli pipelines new <name>

Scaffold a pipeline folder at ./pipelines/<name>/. Valid names must be workflow export identifiers (for example, DemoOcrPipeline).

Creates:

• pipeline.yaml
• src/index.ts
• README.md inside the pipeline
• optional samples/

Exit codes: 0 on success, 1 if the name is invalid or the path already exists.

Example

npx @docufin/cli pipelines new invoice_ingest

npx @docufin/cli pipelines validate <name>

Validate a pipeline locally without compiling. The <name> may be a path; otherwise ./pipelines/<name> is used.

Checks:

• pipeline.yaml (or .json) exists and matches the schema
• Entrypoint exists
• References to local files resolve
• Pipeline name matches the manifest (may warn)

Outputs:

• Human mode: list of checks and readable errors
• JSON mode: { ok, pipelinePath, errors: [{ code, message, file?, line?, col? }] }

Exit codes: 0 when valid, 1 when validation fails.

Example

npx @docufin/cli pipelines validate invoice_ingest

npx @docufin/cli pipelines compile <name> --out <dir>

Create a deterministic build artifact after running validation. --out is required.

Output structure:

<out>/
  manifest.json
  bundle/
    index.js
  source.zip
  artifact.zip
  artifact.sha256
  build-meta.json

Determinism guarantees:

• Stable ordering inside zip files
• Normalized timestamps (no local clock leakage)
• No absolute paths inside artifacts
• artifact.sha256 derived from artifact bytes

Exit codes: 0 on success, 1 on validation or build errors.

Example

npx @docufin/cli pipelines compile invoice_ingest --out .docufin/build/invoice_ingest

npx @docufin/cli pipelines deploy <name> [--message <msg>] [--out <dir>]

End-to-end deployment: validate → compile → package → upload → create revision.

Config requirements: --token and --project (or DOCUFIN_TOKEN / DOCUFIN_PROJECT) must be present.

Behavior:

1. Resolve config and pipeline path
2. Validate pipeline
3. Compile deterministic artifact
4. Upload artifact
5. Create a new revision
6. Print deployment result

Options:

• --message <msg>: release note for the revision
• --out <dir>: reuse a build directory (defaults to .docufin/build/... next to the pipeline config if omitted)
• --json: print only the final JSON object (errors still go to stderr)

Exit codes:

• 0 success
• 1 config or validation error
• 2 network error (timeouts, DNS)
• 3 API/server error (HTTP 4xx/5xx)

JSON success shape:

{
  "ok": true,
  "pipeline": "invoice_ingest",
  "revisionId": "rev_123",
  "artifactSha256": "…",
  "project": "proj_abc"
}

Example

DOCUFIN_TOKEN=token DOCUFIN_PROJECT=proj_123 \
npx @docufin/cli pipelines deploy invoice_ingest --message "CI deploy" --json

npx @docufin/cli evals new <name> --path <dir>

Upload an eval dataset from a local folder. The folder must include a ground-truth/ directory and an inputs/ directory (case-insensitive).

Naming rules:

• Input and ground truth file names must match (ignoring extensions).
• Use a numeric suffix (.x) to represent multiple inputs or outputs for the same base file name.

Example

npx @docufin/cli evals new demo_eval --path deploy/compose/demo-data

npx @docufin/cli uploads upload <paths..>

Upload files or folders to the raw bucket (docufin-raw). Directories are uploaded recursively with their folder structure preserved from the specified folder. Use --prefix to target a path inside the bucket.

Examples

npx @docufin/cli uploads upload ./docs --prefix invoices/2024
npx @docufin/cli uploads upload ./contract.pdf ./receipt.pdf --prefix incoming

Typical workflow

1. Scaffold: npx @docufin/cli pipelines new my_pipeline
2. Develop and run local checks: npx @docufin/cli pipelines validate my_pipeline
3. Produce a deterministic artifact: npx @docufin/cli pipelines compile my_pipeline --out .docufin/build/my_pipeline
4. Deploy from CI or local: npx @docufin/cli pipelines deploy my_pipeline --message "Release notes"