{"id":16254540,"url":"https://github.com/tim-smart/actualbudget-sync","last_synced_at":"2026-03-04T06:15:50.008Z","repository":{"id":254945924,"uuid":"848049898","full_name":"tim-smart/actualbudget-sync","owner":"tim-smart","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-06T01:14:22.000Z","size":362,"stargazers_count":11,"open_issues_count":3,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-06T03:20:02.942Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tim-smart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-27T03:17:16.000Z","updated_at":"2025-09-06T01:13:57.000Z","dependencies_parsed_at":"2024-09-07T01:57:31.650Z","dependency_job_id":"01b11efc-8efe-45fd-b261-46afa2603e3d","html_url":"https://github.com/tim-smart/actualbudget-sync","commit_stats":null,"previous_names":["tim-smart/actualbudget-sync"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/tim-smart/actualbudget-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-smart%2Factualbudget-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-smart%2Factualbudget-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-smart%2Factualbudget-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-smart%2Factualbudget-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tim-smart","download_url":"https://codeload.github.com/tim-smart/actualbudget-sync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-smart%2Factualbudget-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274583125,"owners_count":25311750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T15:22:46.877Z","updated_at":"2026-03-04T06:15:49.996Z","avatar_url":"https://github.com/tim-smart.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @tim-smart/actualbudget-sync\n\nA CLI to sync with Actual Budget.\n\nFeatures:\n\n- Syncs transactions from banks like Akahu and Up to Actual Budget.\n- If the bank supports pending transactions, it will also sync those for\n  real-time updates.\n  - When the pending transaction is cleared, it will update the transaction\n    in Actual Budget with the cleared amount.\n  - If the payee name is updated by the bank, it will also update the\n    transaction in Actual Budget if you haven't renamed it already.\n- Automatically matches the API client with the Actual server version, so you\n  don't have to worry about keeping up-to-date.\n- Supports categorization of transactions for banks that support it.\n\n## Installation\n\nYou can install the CLI using npm:\n\n```bash\nnpm install -g @tim-smart/actualbudget-sync\n```\n\nHere is a quick example of how to use the CLI:\n\n```bash\n# Set the environment variables for Actual Budget\nexport ACTUAL_SERVER=https://actual.example.com\nexport ACTUAL_SYNC_ID=xxx\nexport ACTUAL_PASSWORD=xxx\n# Where to store the sync data. It defaults to ./data\nexport ACTUAL_DATA=/data\n# If you have an encrypted database, set the encryption password\nexport ACTUAL_ENCRYPTION_PASSWORD=xxx\n\n# Set the environment variables for the bank you want to sync with\nexport AKAHU_APP_TOKEN=xxx\nexport AKAHU_USER_TOKEN=xxx\n\nactualsync --bank akahu \\\n  --accounts 'actual-account-id=bank-account-id' \\\n  --accounts 'actual-account-id2=bank-account-id2'\n```\n\nYour sync ID can be found in Actual Budget under Settings \u003e Show Advanced Settings \u003e IDs.\nYour Actual Budget Account IDs can be found from the account URL in the Actual Budget UI (e.g., `https://actual.example.com/accounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).\nYour Akahu Account IDs can be found from the URL on the Akahu web UI (e.g., `https://my.akahu.nz/connections/conn_id/acc_xxxxxxxxxxxxxxxxxxxxxxxxx`).\nYour Up Account IDs can be retrieved via the Up API:\n\n```bash\ncurl https://api.up.com.au/api/v1/accounts \\\n  -H \"Authorization: Bearer $UP_USER_TOKEN\" | jq '.data[].id'\n```\n\n### Docker\n\nYou can also use the pre-built docker image: [`timsmart/actualbudget-sync:main`](https://hub.docker.com/r/timsmart/actualbudget-sync).\n\nHere is an example of how to run the docker image:\n\n```bash\ndocker run -it --rm \\\n  -e ACTUAL_SERVER=https://actual.example.com \\\n  -e ACTUAL_SYNC_ID=xxx \\\n  -e ACTUAL_PASSWORD=xxx \\\n  -e ACTUAL_DATA=/data \\\n  -e AKAHU_APP_TOKEN=xxx \\\n  -e AKAHU_USER_TOKEN=xxx \\\n  -v /path/to/data:/data \\\n  timsmart/actualbudget-sync:main --bank akahu \\\n  --accounts 'actual-account-id=bank-account-id' \\\n  --accounts 'actual-account-id2=bank-account-id2' \\\n```\n\n### Kubernetes\n\nHere is an example of how to run the docker image in a Kubernetes CronJob:\n\n```yaml\napiVersion: batch/v1\nkind: CronJob\nmetadata:\n  name: actualsync\n  namespace: actualsync\nspec:\n  schedule: 7 9-19/2 * * *\n  jobTemplate:\n    spec:\n      template:\n        metadata:\n          labels:\n            job: actualsync\n        spec:\n          containers:\n            - name: sync\n              image: timsmart/actualbudget-sync:main\n              args:\n                - \"--bank\"\n                - akahu\n                - \"--accounts\"\n                - actual-account-id=bank-account-id\n                - \"--accounts\"\n                - actual-account-id2=bank-account-id2\n              imagePullPolicy: Always\n              # put your secrets in a Kubernetes secret\n              envFrom:\n                - secretRef:\n                    name: actualsync-env\n              env:\n                - name: ACTUAL_SERVER\n                  value: https://actual.example.com\n                - name: ACTUAL_DATA\n                  value: /data\n              volumeMounts:\n                - name: data\n                  mountPath: /data\n          restartPolicy: OnFailure\n          volumes:\n            - name: data\n              persistentVolumeClaim:\n                claimName: data\n      parallelism: 1\n      completions: 1\n```\n\n## Development / Debugging\n\nA VSCode launch configuration is included for running the Up Bank sync locally. To use it:\n\n1. Copy `.env.example` to `.env.debug` and fill in your credentials.\n2. Update the `--accounts` arguments in [`.vscode/launch.json`](.vscode/launch.json) with your actual and Up account IDs.\n3. Run the **\"Sync 1000 days Up Bank\"** configuration from the VSCode debugger (Run and Debug panel).\n\n## Usage\n\nHere is a copy of the CLI help:\n\n```\nUSAGE\n  actualsync [flags]\n\nFLAGS\n  --bank choice             Which bank to use\n  --accounts key=value      Accounts to sync, in the format 'actual-account-id=bank-account-id'\n  --categorize, -c          If the bank supports categorization, try to categorize transactions\n  --categories key=value    Requires --categorize to have any effect. Maps the banks values to actual values with the format 'bank-category=actual-category'\n  --timezone string         The timezone to use to display transaction timestamps. Defaults to the bank timezone.\n  --sync-days integer       Number of days to sync (default: 30)\n  --cleared-only, -C        Only sync cleared transactions\n\nGLOBAL FLAGS\n  --help, -h              Show help information\n  --version               Show version information\n  --completions choice    Print shell completion script\n  --log-level choice      Sets the minimum log level\n```\n\nYou will also need to set these environment variables:\n\n```\n# Your Actual Budget server URL\nACTUAL_SERVER=https://actual.example.com\n# Your Actual Budget sync ID and password\nACTUAL_SYNC_ID=xxx\nACTUAL_PASSWORD=xxx\n\n# For the Akahu bank, you will also need to set these:\nAKAHU_APP_TOKEN=xxx\nAKAHU_USER_TOKEN=xxx\n\n# For the Up bank, you will also need to set these:\nUP_USER_TOKEN=xxx\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftim-smart%2Factualbudget-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftim-smart%2Factualbudget-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftim-smart%2Factualbudget-sync/lists"}