ynab-cli 0.1.0__tar.gz

ynab_cli-0.1.0/.env-sample

@@ -0,0 +1,7 @@
+# Make a copy of this file called `.env` and update the variables below if you want to use dotenv files
+
+# Get this from your developer settings https://api.ynab.com/#personal-access-tokens
+YNAB_CLI_ACCESS_TOKEN=YourAccessToken
+
+# Uncomment the below line and update it if you only use ynab-cli with one budget
+# YNAB_CLI_BUDGET_ID=YourBudgetID

ynab_cli-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: jeffsawatzky

ynab_cli-0.1.0/.github/workflows/pr.yml

@@ -0,0 +1,24 @@
+name: pr
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: latest
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked                # abort if the lockfile changes
+      - run: uv run ruff format --check .    # check formatting is correct
+      - run: uv run ruff check --no-fix .    # and linting
+      - run: uv run mypy .                   # typecheck too
+      - run: uv run pytest tests             # then run your tests!
+      - run: uv build                        # make sure the package builds
+      - run: uv run mkdocs build             # make sure the docs build

ynab_cli-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+on:
+  push:
+    tags:
+      - v*
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: latest
+      - name: Build a binary wheel and a source tarball
+        run: uv build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: 'startsWith(github.ref, ''refs/tags/'')'
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: 'https://pypi.org/p/ynab-cli'
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ynab_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.coverage
+.env
+rules.json
+
+__pycache__/
+.my_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.vscode/
+dist/
+site/

ynab_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

ynab_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## v0.1.0 (2025-06-06)
+
+### BREAKING CHANGE
+
+- changes the way the commands need to be run. You now need to specify the "run" command before any of the subcommands
+
+### Feat
+
+- **budgets**: added a command to list all budgets
+- added a feature to prefix unused payees to make them easier to find and delete in ynab
+- added a list all command to payees
+- add a textual based tui
+- use rich for better user feedback
+- implement initial cli
+
+### Refactor
+
+- cleaned up some code, sorted lists, and improved the file selector

ynab_cli-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jeff Sawatzky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ynab_cli-0.1.0/Makefile

@@ -0,0 +1,45 @@
+.PHONY: lint test clean version
+
+.venv: pyproject.toml # the python virtual environment
+	uv sync
+	touch .venv
+
+lint: .venv # run linters and type checkers
+	uv run ruff format .
+	uv run ruff check .
+	uv run mypy .
+
+test: .venv lint # run tests with coverage
+	uv run pytest --cov=src tests
+
+clean: # clean up build artifacts and caches
+	rm -f .coverage
+	rm -rf dist
+	rm -rf htmlcov
+	rm -rf site
+	find . -type f -name .DS_Store | xargs rm -rf
+	find . -type d -name __pycache__ | xargs rm -rf
+	find . -type d -name .mypy_cache | xargs rm -rf
+	find . -type d -name .pytest_cache | xargs rm -rf
+	find . -type d -name .ruff_cache | xargs rm -rf
+	find . -type d -empty -delete
+
+ynab-sdk: # regenerate the YNAB SDK from the OpenAPI spec
+	rm -rf ./src/ynab_cli/adapters/ynab
+	mkdir -p ./src/ynab_cli/adapters/ynab
+	uvx openapi-python-client generate --meta none --url https://api.ynab.com/papi/open_api_spec.yaml --output-path ./src/ynab_cli/adapters/ynab --overwrite
+
+dist: clean # build the distribution package
+	uv build
+
+site: clean # build the documentation site
+	uv run mkdocs build
+
+site-serve: clean # serve the documentation site locally
+	uv run mkdocs serve
+
+site-gh: clean # deploy the documentation site to GitHub Pages
+	uv run mkdocs gh-deploy
+
+version: clean # update the version in pyproject.toml and create a new tag
+	cz bump

ynab_cli-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ynab-cli
+Version: 0.1.0
+Summary: YNAB Command Line Interface
+Project-URL: documentation, https://jeffsawatzky.github.io/ynab-cli/
+Project-URL: source, https://github.com/jeffsawatzky/ynab-cli
+Project-URL: funding, https://github.com/sponsors/jeffsawatzky
+Author: Jeff Sawatzky
+License-File: LICENSE.md
+Keywords: budget,cli,click,textual,ynab
+Requires-Python: >=3.11
+Requires-Dist: attrs~=25.3
+Requires-Dist: click-default-group~=1.2
+Requires-Dist: click~=8.2
+Requires-Dist: httpx~=0.28
+Requires-Dist: python-dotenv~=1.1
+Requires-Dist: rapidfuzz~=3.13
+Requires-Dist: rich~=14.0
+Requires-Dist: rule-engine~=4.5
+Requires-Dist: textual-fspicker~=0.4
+Requires-Dist: textual~=3.3
+Requires-Dist: typing-extensions~=4.14
+Description-Content-Type: text/markdown
+
+# YNAB CLI
+
+A command-line interface for interacting with YNAB (You Need A Budget).
+
+## Usage
+
+Full user documentation available [here](http://jeffsawatzky.github.io/ynab-cli)
+
+## Project Structure
+
+- `src/ynab_cli/`: Main source code
+- `tests/`: Unit and integration tests
+- `docs/`: Documentation (built with MkDocs)
+
+## Getting Started
+
+### Prerequisites
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+### Installation
+
+Clone the repository:
+```sh
+$ git clone https://github.com/jeffsawatzky/ynab-cli.git
+$ cd ynab-cli
+```
+
+Install dependencies with uv:
+```sh
+$ uv sync
+```
+
+### Running the CLI
+
+With uv:
+```sh
+$ uv run ynab-cli --help
+```
+
+## Development
+
+- Source code is in `src/ynab_cli/`.
+- Use feature branches for new work.
+- Follow PEP8 and use type hints where possible.
+
+### Linting & Formatting
+
+```sh
+$ make lint
+```
+
+### Running Tests
+
+```sh
+$ make test
+```
+Or directly with pytest:
+```sh
+uv run pytest
+```
+
+## Documentation
+
+- Docs are in `docs/` and built with MkDocs.
+- To serve docs locally:
+```sh
+$ uv run mkdocs serve
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes. Commits should follow conventional commits. The repo is configured with [commitizen](https://commitizen-tools.github.io/commitizen/)
+4. Push to your fork and open a pull request
+
+Please include tests for new features and bug fixes.
+
+## License
+
+See [LICENSE.md](LICENSE.md)

ynab_cli-0.1.0/README.md

@@ -0,0 +1,82 @@
+# YNAB CLI
+
+A command-line interface for interacting with YNAB (You Need A Budget).
+
+## Usage
+
+Full user documentation available [here](http://jeffsawatzky.github.io/ynab-cli)
+
+## Project Structure
+
+- `src/ynab_cli/`: Main source code
+- `tests/`: Unit and integration tests
+- `docs/`: Documentation (built with MkDocs)
+
+## Getting Started
+
+### Prerequisites
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+### Installation
+
+Clone the repository:
+```sh
+$ git clone https://github.com/jeffsawatzky/ynab-cli.git
+$ cd ynab-cli
+```
+
+Install dependencies with uv:
+```sh
+$ uv sync
+```
+
+### Running the CLI
+
+With uv:
+```sh
+$ uv run ynab-cli --help
+```
+
+## Development
+
+- Source code is in `src/ynab_cli/`.
+- Use feature branches for new work.
+- Follow PEP8 and use type hints where possible.
+
+### Linting & Formatting
+
+```sh
+$ make lint
+```
+
+### Running Tests
+
+```sh
+$ make test
+```
+Or directly with pytest:
+```sh
+uv run pytest
+```
+
+## Documentation
+
+- Docs are in `docs/` and built with MkDocs.
+- To serve docs locally:
+```sh
+$ uv run mkdocs serve
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes. Commits should follow conventional commits. The repo is configured with [commitizen](https://commitizen-tools.github.io/commitizen/)
+4. Push to your fork and open a pull request
+
+Please include tests for new features and bug fixes.
+
+## License
+
+See [LICENSE.md](LICENSE.md)

ynab_cli-0.1.0/docs/index.md

@@ -0,0 +1,42 @@
+# Welcome to YNAB CLI
+
+This is a simple cli/tui application written in python to help manage your YNAB data.
+
+## Requirements
+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) which allows you to easily run python applications.
+- Your [YNAB developer access token](https://api.ynab.com/#personal-access-tokens).
+
+!!! warning
+    Developer access tokens are rate limited to 200 requests per hour. Some of the commands below will provide you an opportunity to enter a new developer access token when the current one has exceeded it's limit. It also seems like there is a limit to how many developer access tokens you can create from the developer settings UI.
+
+- Your YNAB budget ID. Once you have `uv` and your `access token` you can list your budgets by running:
+
+```sh
+$ uvx ynab-cli run --access-token your_access_token budgets list-all
+```
+
+## Usage
+
+!!! note
+    YNAB CLI supports environment variables and dotenv (`.env`) files for specifying options. See the `.env-sample` file for some examples. YNAB CLI looks for the `.env` file in current working directory. If you create a `.env` file with the following information you won't need to keep entering it on the command line.
+
+    ``` title=".env"
+    YNAB_CLI_ACCESS_TOKEN=your_access_token
+    YNAB_CLI_BUDGET_ID=your_budget_id
+    ```
+
+To run the text ui, execute the following command:
+
+```sh
+$ uvx ynab-cli
+```
+
+The individual CLI commands can be similarily run using `uvx`. Full command line usage is below.
+
+::: mkdocs-click
+    :module: ynab_cli.host.cli
+    :command: cli
+    :prog_name: ynab-cli
+    :style: table
+    :list_subcommands: True

ynab_cli-0.1.0/docs/transaction_rules.md

@@ -0,0 +1,42 @@
+!!! note
+    Amounts are in milliunits and can be either positive or negative depending on if they are inflow or outflow.
+
+!!! note
+    To get the category IDs you can use the `ynab run categories list-all` command.
+
+The rules use the [rule-engine](https://zerosteiner.github.io/rule-engine/getting_started.html) library, so read that documentation to figure out how to write the rules. If ANY of the rules in the `rules` list match a transaction then it will be updated with the `patch` details.
+The rules are supplied an instance of a `TransactionDetail`, and the `patch` needs to be an instance of a `SaveTransactionWithIdOrImportId`. Read the [YNAB API documention](https://api.ynab.com/v1) to see what properties are available to base your rules on and update.
+
+This assumes you have a `rules.json` file with your rules to apply. It could look something like this:
+```json
+{
+    "transaction_rules": [
+        {
+            "rules": [
+                "payee_name == 'My Payee' and amount == -213490"
+            ],
+            "patch": {
+                "category_id": "insert the category id you want to assign it to here"
+            }
+        },
+        {
+            "rules": [
+                "payee_name == 'My Split Transaction Payee' and amount == -346500"
+            ],
+            "patch": {
+                "category_id": null,
+                "subtransactions": [
+                    {
+                        "category_id": "insert the first category id you want to assign it to here",
+                        "amount": -51980
+                    },
+                    {
+                        "category_id": "insert the other category id you want to assign it to here",
+                        "amount": -294520
+                    }
+                ]
+            }
+        }
+    ]
+}
+```

ynab_cli-0.1.0/mkdocs.yml

@@ -0,0 +1,28 @@
+site_name: YNAB CLI
+site_url: https://jeffsawatzky.github.io/ynab-cli/
+repo_url: https://github.com/jeffsawatzky/ynab-cli
+
+theme:
+  name: material
+  features:
+    - content.code.copy
+
+plugins:
+  - search
+
+markdown_extensions:
+    - admonition
+    - attr_list
+    - mkdocs-click
+    - pymdownx.details
+    - pymdownx.highlight:
+        anchor_linenums: true
+        line_spans: __span
+        pygments_lang_class: true
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - Transaction Rules: transaction_rules.md

ynab_cli-0.1.0/pyproject.toml

@@ -0,0 +1,133 @@
+[project]
+name = "ynab-cli"
+version = "0.1.0"
+description = "YNAB Command Line Interface"
+readme = "README.md"
+requires-python = ">=3.11"
+license-files = [
+  "LICENSE.md"
+]
+authors = [
+  { name = "Jeff Sawatzky" }
+]
+keywords = [
+  "ynab",
+  "cli",
+  "textual",
+  "click",
+  "budget",
+]
+dependencies = [
+  "attrs~=25.3",
+  "click-default-group~=1.2",
+  "click~=8.2",
+  "httpx~=0.28",
+  "python-dotenv~=1.1",
+  "rapidfuzz~=3.13",
+  "rich~=14.0",
+  "rule-engine~=4.5",
+  "textual-fspicker~=0.4",
+  "textual~=3.3",
+  "typing-extensions~=4.14",
+]
+
+[project.urls]
+documentation = "https://jeffsawatzky.github.io/ynab-cli/"
+source = "https://github.com/jeffsawatzky/ynab-cli"
+funding = "https://github.com/sponsors/jeffsawatzky"
+
+[project.scripts]
+ynab-cli = "ynab_cli.host.cli:main"
+
+
+[dependency-groups]
+dev = [
+  "factory-boy>=3.3.3",
+  "mkdocs-click>=0.9.0",
+  "mkdocs-material>=9.6.14",
+  "mkdocs>=1.6.1",
+  "mypy>=1.16.0",
+  "pytest-asyncio>=1.0.0",
+  "pytest-cov>=6.1.1",
+  "pytest-mock>=3.14.1",
+  "pytest>=8.4.0",
+  "ruff>=0.11.12",
+  "textual-dev>=1.7.0",
+  "types-python-dateutil>=2.9.0.20250516",
+]
+
+
+[tool.mypy]
+python_version = "3.11"
+exclude = [
+  '^tests/.*\.py$'
+]
+pretty = true
+show_column_numbers = true
+show_error_codes = true
+show_error_context = true
+strict = true
+warn_unreachable = true
+enable_error_code = [
+  "explicit-override",
+]
+
+[[tool.mypy.overrides]]
+module = [
+  "click_default_group.*",
+  "factory.*",
+  "rule_engine.*",
+]
+ignore_missing_imports = true
+
+
+[tool.ruff]
+fix = true
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = [
+  "W",   # warnings
+  "I",   # isort
+  "C90", # mccabe
+  "N",   # pep8-naming
+  "UP",  # pyupgrade
+  "S",   # flake8-bandit
+  "B",   # flake8-bugbear
+  "A",   # flake8-builtins
+  "DTZ", # flake8-datetimez
+  "PT",  # flake8-pytest-style
+  "TID", # flake8-tidy-imports
+  "RUF", # ruff specific rules
+]
+extend-ignore = [
+  "S110",   # `try`-`except`-`pass` detected
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["ynab_cli", "tests"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 70
+
+[tool.ruff.lint.flake8-builtins]
+builtins-ignorelist = ["type", "id"]
+
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+annotated_tag = true
+tag_format = "v$version"
+version_scheme = "pep440"
+version_provider = "uv"
+update_changelog_on_bump = true
+major_version_zero = true
+
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

ynab_cli-0.1.0/src/ynab_cli/adapters/rich/io.py

@@ -0,0 +1,38 @@
+from rich import progress as rich_progress
+from rich import prompt as rich_prompt
+from typing_extensions import override
+
+from ynab_cli.domain.ports.io import IO, Progress
+
+
+class RichProgress(Progress):
+    def __init__(self, progress_info: tuple[rich_progress.Progress, rich_progress.TaskID]) -> None:
+        self._progress, self._task_id = progress_info
+
+    @override
+    async def update(
+        self, *, total: float | None = None, completed: float | None = None, advance: float | None = None
+    ) -> None:
+        task = self._progress.tasks[self._task_id]
+        if not task.started:
+            self._progress.start_task(self._task_id)
+        self._progress.update(self._task_id, total=total, completed=completed, advance=advance)
+
+
+class RichIO(IO):
+    def __init__(self, progress_info: tuple[rich_progress.Progress, rich_progress.TaskID]) -> None:
+        progress, _ = progress_info
+        self._progress = progress
+        self.progress = RichProgress(progress_info)
+
+    @override
+    async def prompt(self, prompt: str, password: bool = False) -> str:
+        try:
+            self._progress.stop()
+            return rich_prompt.Prompt.ask(prompt, console=self._progress.console, password=password)
+        finally:
+            self._progress.start()
+
+    @override
+    async def print(self, message: str) -> None:
+        return self._progress.console.print(message)