mirror of
https://github.com/actualbudget/actual.git
synced 2026-07-16 07:04:23 -05:00
[Feature] Standardized CLI Interface for API Interaction (JSON-RPC over Stdin) #2832
Closed
opened 2026-02-28 20:30:00 -06:00 by GiteaMirror
·
5 comments
No Branch/Tag Specified
master
dependabot/npm_and_yarn/npm_and_yarn-cd62b4b37a
api-browser-custom-data-dir
tabedzki/feat/replacing-month-picker-with-day-picker
delay-initial-sync-until-loaded
jfdoming/mobile-app-build
cross-version-sync-compat
jfdoming/api-tokens-part-1
jfdoming/api-tokens-part-2
jfdoming/api-tokens-part-3
jfdoming/mobile-app-updates
claude/budget-version-migration-compat-151jlr
claude/worker-error-serialization-9iqtl7
claude/react-table-library-research-afx83z
claude/issue-8401-regression-test-9nw9l3
jfdoming/mobile-app-foundation-part-1
jfdoming/mobile-app-scaffold
release
ai-fix-cleanup-def-8290
claude/relaxed-shannon-jusywa
claude/fervent-keller-s6f2fq
claude/determined-feynman-st1y9z
claude/wizardly-einstein-vi2wce
claude/sweet-albattani-7nseio
feat/bank-sync-per-budget-file
claude/affectionate-cannon-y0kc82
claude/dependabot-findings-m9pgmb
claude/mac-app-ios-publish-zjs1lz
claude/vigilant-tesla-aiiyos
depot-migrate-secrets-1781296330308
claude/quirky-cerf-v5qck7
claude/animation-removal-alternative-2etfh1
claude/netlify-preview-comments-consolidate-9XPYa
osc/7391-error-boundaries-reports
claude/pensive-dijkstra-7DYui
claude/server-app-version-mismatch-HTCGv
claude/pr-8027-review-feedback-mELuO
claude/zealous-wozniak-e5pO0
claude/intelligent-heisenberg-BSHJq
claude/translation-download-refactor-jFRsO
claude/mobile-performance-ideas-G9PAO
claude/github-issue-7988-5A5ly
blacksmith-migration-ff70d2d
claude/great-mayer-KRvOk
claude/react-native-ios-compilation-fcJh5
claude/serene-goldberg-58xv0
claude/kind-euler-LVG3K
release-automation/edge-nightly
7710-bundle-migrations
claude/fix-docker-build-error-WMfed
claude/llm-compatible-release-notes-t20Nr
7710-tests-tdd
cursor/transaction-table-rewrite-f077
claude/plan-ci-secure-context-OtEe1
claude/fix-issue-7667-DPXi3
cursor/resolve-pr-7449-ee11
claude/fix-typescript-build-error-JPtZ5
copilot/add-repository-configs-to-packages
worktree-compressed-drifting-ritchie
claude/api-consumer-verification-kfz1K
pr-7454
claude/fix-issue-7410-LLLQ4
revert-7281-generate-icons
react-query-useSchedules
copilot/sub-pr-6140
package-upgrades
v26.7.0
v26.6.0
v26.5.2
v26.5.1
v26.5.0
v26.4.0
v26.3.0
v26.2.1
v26.2.0
v26.1.0
v25.12.0
v25.11.0
v25.10.0
v25.9.0
v25.8.0
v25.7.1
v25.7.0
v25.6.1
v25.6.0
v25.5.0
v25.4.0
v25.3.1
v25.3.0
v25.2.1
v25.2.0
v25.1.0
v24.12.0
v24.11.0
v24.10.1
v24.10.0
v24.9.0
v24.8.0
v24.7.0
v24.6.0
v24.5.0
v24.4.0
v24.3.0
v24.2.0
v24.1.0
v23.12.0
v23.11.0
v23.10.0
v23.9.0
v23.8.1
v23.8.0
v23.7.2
v23.7.1
v23.7.0
v23.6.0
v23.5.0
v23.4.2
v23.4.1
v23.4.0
v23.3.2
v23.3.0
v23.2.9
v23.2.5
v23.1.12
v22.12.9
Labels
Clear labels
AI generated
API
bank sync
budgeting
bug
can’t replicate
dependencies
docker
documentation
electron
experimental feature
feature
feedback
goal templates
good first issue
help wanted
importers
maintenance
needs info
needs testing
needs triage
needs votes
openid
payees
pull-request
regression
reports
responsive
rules
schedules
server
✨ merged
split transactions
tech debt
tech-support
theme
transaction import
transaction reconciliation
transactions
translations
upstream
user interface
✅ approved
wontfix
Mirrored from GitHub Pull Request
Milestone
No items
No Milestone
Projects
Clear projects
No project
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/actual#2832
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @Zeor-Xain on GitHub (Jan 17, 2026).
Verified feature request does not already exist?
💻
Pitch: what problem are you trying to solve?
The current
@actual-app/apiis excellent but strictly tied to the Node.js ecosystem. As the documentation explicitly states: "Actual does not expose HTTP endpoints that can be called."This architectural choice creates a significant barrier for users and developers who work with other languages (Bash scripts, Python, Go, Rust) or environments where a persistent Node.js process or a custom HTTP wrapper server is overkill or technically infeasible.
To interact with Actual programmatically today, a non-Node developer must:
This fragmentation discourages the creation of community tools (like importers, reporters, or automation bots) in languages other than JavaScript. I recently implemented a custom bridge to import transactions from Python via
docker/podman exec, and while effective, it felt like reinventing a wheel that could be a standard part of the toolkit.Describe your ideal solution to this problem
I suggest adding a Standardized CLI mode to the
@actual-app/apipackage (or a companion package) that implements a simple "JSON-RPC over Stdin" interface.The Mechanism
Instead of writing custom JS scripts for every task, the user would invoke a standard entry point (e.g.,
actual-cli run-bridge) that:Example Workflow
A Python script (or any language) could simply spawn the process and pipe data:
Input (STDIN):
Output (STDOUT):
Why "JSON over Stdin"?
docker exec -i actual-node actual-cli < payload.json).Teaching and learning
Discoverability
This feature positions Actual Budget as "Language Agnostic" for automation. Documentation could feature a "Universal API Usage" section showing examples in Bash, Python and Go, all calling the same underlying
actual-clicommand.Documentation Needs
STDOUTfor data andSTDERRfor logs (to avoid parsing errors if debug logs pollute the output).Potential Pitfalls
Prototype use case
ActualAPI, running side-by-side with theactual_actual_server_1container, configured to use the server container's network and with the data directory mounted at/data.ActualAPIcontainer (npm install --location=global @actual-app/api), serving with a custombridge.jsfor@actual-app/apiactions./bridge.js (expand)
Can run with success passing a json payload to
stdinin terminal:@github-actions[bot] commented on GitHub (Jan 17, 2026):
✨ Thanks for sharing your idea! ✨
This repository uses a voting-based system for feature requests. While enhancement issues are automatically closed, we still welcome feature requests! The voting system helps us gauge community interest in potential features. We also encourage community contributions for any feature requests marked as needing votes (just post a comment first so we can help guide you toward a successful contribution).
The enhancement backlog can be found here: https://github.com/actualbudget/actual/issues?q=label%3A%22needs+votes%22+sort%3Areactions-%2B1-desc+
Don't forget to upvote the top comment with 👍!
@MatissJanis commented on GitHub (Jan 17, 2026):
👋 Feel free to implement this and we'll be happy to link to it in the community projects page: https://actualbudget.org/docs/community-repos
@Zeor-Xain commented on GitHub (Jan 17, 2026):
TL;DR - Feature Request: Actual CLI (JSON-RPC)
The Problem:
The current Actual Budget API is an NPM package exclusive to Node.js. This forces developers using other languages (Python, Go, Rust, Bash) to
either write custom wrappers or learn JavaScript just to move data.
The Solution:
Implement an official Command Line Interface (CLI) that operates via STDIN/STDOUT using JSON.
How it would work:
Key Benefits:
@Zeor-Xain commented on GitHub (Jan 17, 2026):
I understand that the current model, focused on Node.js via
@actual-app/api, is excellent for the primary use case:Custom importers and exporters.
However, the accessibility of the API would improve significantly by adding direct Shell communication.
A "JSON-RPC over Stdin" approach seems to align well with this requirement, being both agnostic and straightforward. This covers the most elementary use case: a Shell pipeline designed to receive a return value.
The inability of the
@actual-app/apito interact with the Shell in a pipeline seems to be a fundamental gap in its current architecture.The choice of "JSON-RPC over Stdin" fits the current API structure well:
In fact, the current "Code-level API" is quite restrictive, and a significant gap. Communicating with the shell would expand the API to also be IPC-based. Therefore, this feature seems appropriate to reside within the official API package, unlike community projects that merely build upon it.
Residing in the official package also brings benefits in security and maintenance, but above all, in communication standardization.
I believe the implementation of this feature addresses these challenges with an effort that is consistent with the benefits.
Question for the maintainers:
I am happy to provide a functional prototype, even though I am unable to join the maintainers at this time:
This is successfully executed in the shell by passing a JSON payload to standard input (stdin):
@MatissJanis commented on GitHub (Jan 17, 2026):
No.
But feel free to build this as a separate project in your github account. And then you can share it with the community via the community projects page I linked above.