Acumatica Bridge

Acumatica Bridge is a secure, read-only command-line client for Acumatica ERP. It gives coworkers and automation a consistent acu command for browser sign-in, connection diagnostics, bounded record lookup, and safe export.

The public core is intentionally narrow. Version 0.1 has no create, update, delete, arbitrary-request, plugin auto-load, browser-scraping, public-server, or AI data-sharing surface.

This is an independent, unofficial project and is not affiliated with or endorsed by Acumatica, Inc.

Install

Release binaries contain Node.js, so coworkers do not need Node, npm, Homebrew, or developer tools.

macOS or Linux:

curl -fsSLO https://raw.githubusercontent.com/Sage100/acumatica-bridge/v0.1.1/scripts/install.sh
less install.sh
ACU_VERSION=v0.1.1 ACU_ALLOW_UNSIGNED=1 sh install.sh

Windows PowerShell:

$Version = "v0.1.1"
Invoke-WebRequest "https://raw.githubusercontent.com/Sage100/acumatica-bridge/$Version/scripts/install.ps1" -OutFile install-acu.ps1
Get-Content .\install-acu.ps1
Unblock-File .\install-acu.ps1
& .\install-acu.ps1 -Version $Version -AllowUnsigned

The examples pin both installer and binary to a reviewed release. The scripts verify the release SHA-256 checksum before installing. ACU_ALLOW_UNSIGNED=1 / -AllowUnsigned is an explicit pilot-only exception; remove it after company signing is configured. See distribution notes before a broad rollout.

Developers with Node.js 24 can build from source:

npm ci
npm run check
npm link
acu --version

First use

An Acumatica administrator must first register a public OAuth client that allows Authorization Code + PKCE and this exact redirect URI:

http://127.0.0.1:8794/callback

Then create a profile using the URL, company, and public client ID supplied by IT:

acu setup \
  --name company \
  --base-url https://acumatica.example.com/AcumaticaERP \
  --company ExampleCompany \
  --client-id desktop-cli \
  --set-default

acu auth login
acu doctor

No OAuth client secret belongs on a coworker computer. See administrator setup for server-side prerequisites.

Everyday commands

# Connection and profile status
acu doctor
acu profiles list
acu auth status

# Endpoint discovery
acu endpoints list
acu endpoint resolve

# Bounded, read-only records
acu list Customer --top 20 --select CustomerID,CustomerName,Status
acu get Customer CUSTOMER-ID

# Safe export (10,000-record and 100 MB defaults/caps)
acu export Customer --filter "Status eq 'Active'" --format csv

Use --json for one machine-readable JSON document on commands that print records or status. Exports support lossless JSON/NDJSON and spreadsheet-safe CSV. Existing output files are never replaced unless --force is explicit.

Configuration and data locations

Profiles contain only nonsecret settings. OAuth access and refresh tokens are stored in a per-user local application-data file, atomically written with private Unix permissions where supported.

Platform	Default location
macOS	~/Library/Application Support/Acumatica Bridge/
Windows	%LOCALAPPDATA%\Acumatica Bridge\
Linux	${XDG_CONFIG_HOME:-~/.config}/acumatica-bridge/

Default exports are written under that same per-user application directory, not the current repository or a synced working folder. Set ACU_CONFIG_DIR only for portable/test installations. ACU_ACCESS_TOKEN can supply a temporary, unsaved automation token.

Token files are not an OS credential vault yet. Protect the user account and disk; use FileVault or BitLocker for company deployments. Keychain/Credential Manager integration is on the roadmap.

Security model

• HTTPS is mandatory except loopback development.
• OAuth authorize and token endpoints must remain on the configured Acumatica origin.
• PKCE uses S256, random state, and a loopback-only callback listener.
• Tokens are cryptographically bound to the profile URL, company, client ID, token endpoint, and scope.
• The HTTP client exposes GET operations only, refuses absolute request paths, blocks redirects, caps responses, retries bounded transient failures, and never logs response bodies or query values.
• Audits contain request metadata only; record keys are replaced with :key.
• Exports have record and memory caps, private-file defaults, no-clobber writes, CSV formula protection, and terminal-control sanitization.

Read the full security design and security policy. Never paste tokens, internal URLs, customer data, or raw ERP responses into a public issue.

Project status

Version 0.1 is a read-only pilot. Company-specific workflows, mappings, write operations, report browser automation, local caches, dashboards, and integrations belong in separately reviewed packages. See the architecture, roadmap, and changelog.

Licensed under the Apache License 2.0.