Digitrad OpenAPI CLI

Agent-oriented CLI for interacting with Digitrad SaaS APIs through the published OpenAPI documents.

Usage

Run the CLI through Bun:

bunx --bun digitrad-openapi-cli <args>

If an npm release is available but Bun is still using an earlier cached package, refresh it once and then return to the unversioned command:

bunx --bun digitrad-openapi-cli@latest help

Default API Base

https://digitrad.trade/_api

Supported Domains

• admin
• event
• internal
• boueki
• fwdpro
• pmt
• currency
• file
• ai

Commands

All outbound HTTP requests identify the CLI with the User-Agent value digitrad-openapi-cli/<version>.

exec

bunx --bun digitrad-openapi-cli exec PATH --domain domain [--base URL] [--user-email email] [--method METHOD] [--header "Key: Value"...] [--query-json @file|@-] [--body-json @file|@-] [--form "key=value"...] [--this-request-is-confirmed-by-the-user]

The request URL is reconstructed as:

{base URL}/{domain}{PATH}

--query-json and --body-json accept only @file or @-; inline JSON is rejected. File and standard-input JSON may contain one leading UTF-8 byte order mark (BOM).

Non-2xx HTTP responses are printed as JSON on stderr with error.status, error.statusText, error.headers, and error.body.

Examples:

bunx --bun digitrad-openapi-cli exec /v1/me --domain admin --user-email [email protected]

bunx --bun digitrad-openapi-cli exec /v1/users \
  --domain admin \
  --user-email [email protected] \
  --query-json @query.json

bunx --bun digitrad-openapi-cli exec /v1/companies/{uuid}/forwarding/files \
  --domain internal \
  --method PUT \
  --user-email [email protected] \
  --form "files=@./document.pdf;type=application/pdf"

Use repeated --form values for multipart requests. --form name=value sends a text field. --form name=@path sends a local file. File references support ;filename=... and ;type=... overrides, and @@ escapes literal text values that start with @. Do not pass a Content-Type header with --form; the CLI lets fetch generate the required multipart boundary.

When --user-email is used, the CLI enforces the stored write posture for that {base URL, user email} tuple before mutating requests are sent. --this-request-is-confirmed-by-the-user is a one-shot confirmation flag for exactly one mutating exec call when the stored posture is write-on-confirm.

upload

bunx --bun digitrad-openapi-cli upload URL --file path --method METHOD --content-type MIME [--header "Key: Value"...]

This sends the file as the raw request body to the exact URL provided. It is meant for signed upload URLs, such as temporary Google Cloud Storage URLs, and intentionally does not use --base, --domain, --user-email, or stored Digitrad auth.

Example:

bunx --bun digitrad-openapi-cli upload "https://signed-upload-url.example/..." \
  --method PUT \
  --content-type image/jpeg \
  --file ~/Downloads/photo.jpg

auth

bunx --bun digitrad-openapi-cli auth --user-email email [--base URL] [--token-store os|file] [--write-posture read-only|write-on-confirm|write-allowed]
bunx --bun digitrad-openapi-cli auth list [--base URL]
bunx --bun digitrad-openapi-cli auth status --user-email email [--base URL]
bunx --bun digitrad-openapi-cli auth refresh --user-email email [--base URL]
bunx --bun digitrad-openapi-cli auth refresh --all [--base URL]
bunx --bun digitrad-openapi-cli auth remove --user-email email [--base URL]

• Prompts for the password interactively.
• Stores the authenticated session in the OS credential store by default.
• --token-store file explicitly selects an unencrypted per-session JSON file under the CLI state directory. This is less secure than the OS credential store and is never selected automatically.
• The selected backend is tracked for subsequent status, list, refresh, automatic refresh, authenticated execution, and removal commands.
• Stores a write posture per {base URL, user email} tuple in the tracked auth state.
• --write-posture defaults to read-only.
• read-only blocks mutating exec requests.
• write-on-confirm requires --this-request-is-confirmed-by-the-user on the exact mutating exec request.
• write-allowed permits mutating exec requests without the extra confirmation flag.
• Tracks known auth tuples in an external local state file so they can be listed, refreshed in bulk, and removed without storing mutable state in the repository.
  • macOS default: ~/Library/Application Support/STANDAGE/digitrad-openapi-cli/auth-state.json
  • Windows default: %LOCALAPPDATA%\\STANDAGE\\digitrad-openapi-cli\\State\\auth-state.json
  • Override: DIGITRAD_OPENAPI_CLI_STATE_DIR
• File-backed tokens use <state directory>/tokens/<session hash>.json. On POSIX systems, the token directory is restricted to mode 0700 and token files to mode 0600; on Windows, the state directory inherits the current user's ACL.
• auth list shows the tracked auth inventory grouped by {base URL, user email}, including the token backend, local token presence, decoded access-token expiry, and whether the session has been marked unretriable.
• auth status reports the token backend, stored write posture, whether a stored session exists, whether access/refresh tokens are present, and the locally decoded access-token expiry if the access token is a JWT.
• auth refresh proactively rotates the stored refresh token so the session can be renewed before the next 401.
• auth refresh --all walks the tracked auth inventory and refreshes every retriable session for the selected base URL or for all tracked bases when --base is omitted.
• auth remove deletes the selected backend's stored tokens and the tracked auth inventory entry for the selected {base URL, user email} tuple.

describe

bunx --bun digitrad-openapi-cli describe --domain domain [--base URL] [--with-examples] verb:/path [verb:/path ...]

Outputs concise endpoint documentation, including parameters, request bodies, and responses.

When --with-examples is provided, any endpoint-level OpenAPI example or examples entries are included in the output.

list-tags

bunx --bun digitrad-openapi-cli list-tags --domain domain [--base URL]

Lists tags from the cached or downloaded OpenAPI document with endpoint counts.

list

bunx --bun digitrad-openapi-cli list --domain domain [--base URL] [--keyword keyword ...] [--page N] [--page-size N]

• Returns at most 20 endpoints per page.
• Keyword filters are combined with OR.
• Matches against tags, path, summary, description, operation id, and method.

self-update

bunx --bun digitrad-openapi-cli self-update

This compatibility command does not inspect or replace process.execPath, does not update Bun, and does not write files. It prints the one-off bunx --bun digitrad-openapi-cli@latest help cache-refresh command.

version

bunx --bun digitrad-openapi-cli version
bunx --bun digitrad-openapi-cli --version

Prints the embedded CLI version. This is the same version used in the User-Agent header.

OpenAPI Cache

• Specs are downloaded from {base URL}/{domain}/_documentation-json.
• Cache TTL is 30 minutes.
• If refresh fails but a cached spec exists, the CLI falls back to the stale cached copy.
• Cached OpenAPI documents are stored in an OS-native cache directory.
  • macOS default: ~/Library/Caches/STANDAGE/digitrad-openapi-cli/
  • Windows default: %LOCALAPPDATA%\\STANDAGE\\digitrad-openapi-cli\\Cache\\
  • Override: DIGITRAD_OPENAPI_CLI_CACHE_DIR
  • If the preferred cache directory is not writable, the CLI falls back to a temporary cache directory automatically.