frappectl 0.13.1__tar.gz

frappectl-0.13.1/.github/workflows/ci.yml

@@ -0,0 +1,216 @@
+name: CI
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest
+
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        with:
+          python-version: "3.14"
+
+      - name: Run pre-commit
+        env:
+          SKIP: no-commit-to-branch
+        run: uvx pre-commit run --all-files --show-diff-on-failure
+
+  # The integration suite runs on pull requests (and manual dispatches) but not
+  # on push, so branch pushes stay fast. Its result is rolled up by the `ci`
+  # gate job below.
+  integration:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'push'
+
+    services:
+      mariadb:
+        image: mariadb:11.4
+        env:
+          MARIADB_ROOT_PASSWORD: root
+        ports:
+          - 3306:3306
+        # tmpfs for the datadir keeps the ephemeral CI DB fast (mirrors Frappe's own CI).
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=10
+          --tmpfs=/var/lib/mysql:rw,noexec,nosuid,size=2g
+
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd="redis-cli ping"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=10
+
+    env:
+      # The site the CLI talks to. Served as the bench's default site, so the
+      # CLI can reach it over plain 127.0.0.1 without any /etc/hosts juggling.
+      SITE: test.localhost
+
+    steps:
+      - name: Checkout frappectl
+        uses: actions/checkout@v7
+
+      # --- The CLI under test (managed by uv, isolated from the bench env) ---
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        with:
+          python-version: "3.14"
+
+      - name: Install frappectl
+        run: uv sync --extra dev
+
+      # --- Toolchain for provisioning a Frappe bench ---
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      # Warm yarn's download cache so `bench init` installs frappe's node deps
+      # from disk instead of re-fetching them from the registry every run. The
+      # run_id in the key always writes a fresh cache; restore-keys pulls the
+      # newest prior one so it stays current as frappe's deps drift.
+      - name: Cache yarn packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/yarn
+          key: yarn-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: |
+            yarn-${{ runner.os }}-
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential pkg-config \
+
+      - name: Install Bench
+        run: |
+          uv tool install frappe-bench
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Provision a Frappe site
+        run: |
+          set -euo pipefail
+
+          bench init --skip-assets --no-backups \
+            --skip-redis-config-generation \
+            --frappe-branch develop ~/frappe-bench
+          cd ~/frappe-bench
+
+          # Point every redis role at the service container instead of bench's
+          # own bundled redis, so we don't need honcho/`bench start` running.
+          bench set-config -g redis_cache    "redis://localhost:6379"
+          bench set-config -g redis_queue    "redis://localhost:6379"
+          bench set-config -g redis_socketio "redis://localhost:6379"
+          bench set-config -g use_mysqlclient 0
+
+          # DB root creds + admin password via global config — the path Frappe's
+          # own CI uses, rather than the (renamed) new-site CLI flags.
+          bench set-config -g root_login root
+          bench set-config -g root_password root
+          bench set-config -g admin_password admin
+
+          bench new-site "$SITE" \
+            --db-type mariadb \
+            --db-host 127.0.0.1 \
+            --db-name test_frappe \
+            --db-password test_frappe \
+            --verbose
+          bench use "$SITE"
+
+      - name: Generate Administrator API keys
+        run: |
+          set -euo pipefail
+          cd ~/frappe-bench
+          bench --site "$SITE" execute \
+            frappe.core.doctype.user.user.generate_keys \
+            --kwargs '{"user": "Administrator"}' > keys.out
+          python - <<'PY'
+          import json, os, re
+          raw = open(os.path.expanduser("~/frappe-bench/keys.out")).read()
+          match = re.search(r'\{[^{}]*"api_secret"[^{}]*\}', raw, re.S)
+          keys = json.loads(match.group(0))
+          with open(os.environ["GITHUB_ENV"], "a") as env:
+              env.write(f"FRAPPE_API_KEY={keys['api_key']}\n")
+              env.write(f"FRAPPE_API_SECRET={keys['api_secret']}\n")
+          PY
+
+      - name: Serve the site
+        run: |
+          cd ~/frappe-bench
+          bench start &
+          for i in $(seq 1 30); do
+            if curl -sf http://test.localhost:8000/api/method/ping >/dev/null; then
+              echo "site is up"; exit 0
+            fi
+            sleep 2
+          done
+          echo "site did not come up in time" >&2
+          exit 1
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration -m integration -v
+        env:
+          FRAPPE_SITE: http://test.localhost:8000
+
+  # Single roll-up status check — make THIS the only required check in the
+  # ruleset. It aggregates the individual jobs so the required-checks list never
+  # has to be maintained. `!cancelled()` lets it run even when integration is
+  # skipped (on push); it then fails unless every job that should have run for
+  # this event succeeded.
+  ci:
+    name: ci
+    runs-on: ubuntu-latest
+    needs: [test, pre-commit, integration]
+    if: ${{ !cancelled() }}
+    steps:
+      - name: Verify all checks passed
+        run: |
+          echo "test=${{ needs.test.result }} pre-commit=${{ needs['pre-commit'].result }} integration=${{ needs.integration.result }} (event=${{ github.event_name }})"
+
+          # Unit tests and linters must pass on every event.
+          [ "${{ needs.test.result }}" = "success" ] || { echo "::error::unit tests failed"; exit 1; }
+          [ "${{ needs['pre-commit'].result }}" = "success" ] || { echo "::error::pre-commit failed"; exit 1; }
+
+          # Integration runs on everything except push; require it there, ignore
+          # its (skipped) result on push.
+          if [ "${{ github.event_name }}" != "push" ]; then
+            [ "${{ needs.integration.result }}" = "success" ] || { echo "::error::integration tests failed"; exit 1; }
+          fi
+
+          echo "All required checks passed."

frappectl-0.13.1/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish
+
+# Publish to PyPI whenever semantic-release cuts a GitHub release. This fires
+# because release.yml authenticates with a PAT (RELEASE_TOKEN) — releases
+# created with the default GITHUB_TOKEN would not trigger other workflows.
+#
+# Authentication is PyPI "trusted publishing" (OIDC): no API token secret.
+# PyPI must be configured with a trusted publisher for the `frappectl`
+# project pointing at this repo, workflow `publish.yml`, environment `pypi`.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/frappectl/
+    permissions:
+      id-token: write # mint the OIDC token PyPI trusted publishing verifies
+
+    steps:
+      # Build from the released tag, not the branch tip: a commit landing on
+      # develop between the release and this run must not leak into the wheel.
+      - name: Checkout release tag
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        with:
+          python-version: "3.14"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # Catch a broken artifact before it is immortalised on PyPI: install the
+      # wheel into a clean environment and run both entry points.
+      - name: Smoke-test the wheel
+        run: |
+          uvx --from ./dist/frappectl-*.whl frappectl --version
+          uvx --from ./dist/frappectl-*.whl fr guide > /dev/null
+
+      - name: Publish to PyPI
+        run: uv publish

frappectl-0.13.1/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+# Every push to develop cuts a release. No CI gate is needed here: nothing
+# reaches develop except through the merge queue, which already runs the full
+# suite (unit tests, linters, integration) before fast-forwarding the branch.
+# semantic-release is a no-op when a push carries no releasable commits (e.g.
+# the bot's own `chore(release):` commit), so re-runs are harmless.
+on:
+  push:
+    branches: [develop]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Entire Repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      # `uv` is needed by the semantic-release prepare step, which runs
+      # `uv lock` to keep the lockfile's project version in sync with the
+      # bumped pyproject.toml (both are committed in the release commit).
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        with:
+          python-version: "3.14"
+
+      - name: Setup dependencies
+        run: |
+          npm install @semantic-release/git @semantic-release/exec --no-save
+
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          GIT_AUTHOR_NAME: "Frappe CLI Bot"
+          GIT_AUTHOR_EMAIL: "developers@frappe.io"
+          GIT_COMMITTER_NAME: "Frappe CLI Bot"
+          GIT_COMMITTER_EMAIL: "developers@frappe.io"
+        run: npx semantic-release

frappectl-0.13.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

frappectl-0.13.1/.pre-commit-config.yaml

@@ -0,0 +1,56 @@
+exclude: '.git'
+default_stages: [pre-commit]
+default_install_hook_types: [pre-commit, commit-msg]
+fail_fast: false
+
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ".*json$|.*txt$|.*csv|.*md|.*svg"
+      - id: no-commit-to-branch
+        args: ['--branch', 'develop']
+      - id: check-merge-conflict
+      - id: check-ast
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff
+        name: "Run ruff import sorter"
+        args: ["--select=I", "--fix"]
+
+      - id: ruff
+        name: "Run ruff linter"
+
+      - id: ruff-format
+        name: "Run ruff formatter"
+
+  # mypy runs through uv so it resolves against the locked project + typed deps
+  # (typer, httpx, rich…). An isolated pre-commit env wouldn't see them and would
+  # drown in false import errors. It reads its config (strict, files = ["src"])
+  # from pyproject.toml, so it types the whole package regardless of staged files.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: "Run mypy (strict)"
+        entry: uv run --extra dev mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true
+
+
+ci:
+    autoupdate_schedule: weekly
+    # `uv` isn't available on the hosted pre-commit.ci runners, so the local
+    # mypy hook can't run there. It still runs locally and in the GitHub Actions
+    # `pre-commit` job (which installs uv) — the check that actually gates merges.
+    skip: [mypy]
+    submodules: false

frappectl-0.13.1/.releaserc

@@ -0,0 +1,19 @@
+{
+	"branches": ["develop"],
+	"plugins": [
+		"@semantic-release/commit-analyzer",
+		"@semantic-release/release-notes-generator",
+		[
+			"@semantic-release/exec", {
+				"prepareCmd": "sed -i -E 's/^version = \"[0-9]+\\.[0-9]+\\.[0-9]+\"/version = \"${nextRelease.version}\"/' pyproject.toml && uv lock"
+			}
+		],
+		[
+			"@semantic-release/git", {
+				"assets": ["pyproject.toml", "uv.lock"],
+				"message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
+			}
+		],
+		"@semantic-release/github"
+	]
+}

frappectl-0.13.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frappe Technologies Pvt Ltd
+
+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.

frappectl-0.13.1/PHILOSOPHY.md

@@ -0,0 +1,8 @@
+# Philosophy
+
+- **For humans and agents, equally.** A TTY gets rich tables and prompts; a pipe (or `--json`) gets clean JSON on stdout and nothing else. Same command, both audiences.
+- **A thin, honest wrapper.** Verbs map to the Frappe REST API v2 with little magic, and `api` is always the escape hatch — the CLI never hides the platform underneath.
+- **Predictable I/O contract.** stdout is data, stderr is chatter. Exit `0`/`1`/`2`. Errors are plain text with a tip pointing at the fix.
+- **Safe by default.** Mutations refuse to run non-interactively without `--yes`; updates are optimistic unless `--force`.
+- **Credentials are the human's job.** Key/secret live in env or the OS keyring — never plaintext, never mutated by the CLI, never set up for you.
+- **Self-orienting.** `guide` and `doctype show` let anyone learn the surface before touching a live site. Orient, don't guess.

frappectl-0.13.1/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: frappectl
+Version: 0.13.1
+Summary: frappectl — a command-line client for Frappe sites, built for humans and AI agents.
+Project-URL: Homepage, https://github.com/frappe/frappectl
+Author-email: Ankush Menat <ankush@frappe.io>
+License: MIT
+License-File: LICENSE
+Keywords: api,cli,erpnext,frappe
+Requires-Python: >=3.10
+Requires-Dist: authlib>=1.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=24.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# frappectl
+
+[![CI](https://github.com/frappe/frappectl/actions/workflows/ci.yml/badge.svg)](https://github.com/frappe/frappectl/actions/workflows/ci.yml)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](#license)
+
+A command-line REST API v2 client for Frappe v16+ — built for humans and AI agents.
+
+Using an agent? Start with `frappectl guide`. It fits site selection, core verbs,
+filtering and the raw-API escape hatch on one screen.
+
+```sh
+frappectl auth login https://erp.example.com         # key/secret → OS keyring
+frappectl -s raven doc list "Raven Channel" --json    # -s/--site selects a profile
+
+frappectl doc list "Sales Invoice" -f status=Overdue -f 'grand_total>1000' \
+  --fields name,customer,grand_total --all --json
+frappectl doc get "Sales Invoice" SINV-0001
+frappectl doc create ToDo --set description="Follow up" --set priority=High
+cat invoice.json | frappectl doc create "Sales Invoice"
+frappectl doc submit "Sales Invoice" SINV-0001
+frappectl doc delete ToDo abc123 --yes
+
+frappectl doctype show "Sales Invoice" --json         # discover the schema first
+frappectl report run "Accounts Receivable" -f company="Frappe" --json
+frappectl file upload ./contract.pdf --doctype "Sales Invoice" --name SINV-0001 --private
+frappectl api method/frappe.client.get_count -F doctype=User
+frappectl api method/gameplan.api.get_unread_count    # raw API, when verbs aren't enough
+```
+
+## Install
+
+```sh
+uv tool install frappectl
+# or: pip install frappectl
+# development version: uv tool install git+https://github.com/frappe/frappectl
+```
+
+This installs two commands: `frappectl` and its short alias `fr`.
+
+## Authentication
+
+frappectl supports 3 authentication paths.
+
+### Environment variables
+
+Environment variables always win and never touch the keyring.
+
+```sh
+export FRAPPE_SITE=https://erp.example.com
+export FRAPPE_API_KEY=xxxxxxxx
+export FRAPPE_API_SECRET=yyyyyyyy
+```
+
+### Stored profiles
+
+Generate an API key + secret from **User → Settings → API Access**, then log in:
+
+```sh
+frappectl auth login https://erp.example.com
+frappectl auth login https://raven.example.com --name raven
+frappectl auth login https://raven.example.com --name raven --default
+frappectl auth list
+frappectl auth default raven                          # change the default
+frappectl -s raven doc list "Raven Channel"           # select per command
+frappectl auth whoami
+```
+
+The site URL lives in `~/.config/frappe/config.json`; the secret lives in the **OS
+keyring**. There is no plaintext fallback. If the machine has no keyring, use environment
+variables.
+
+### OAuth
+
+Interactive login selects OAuth by default. It stores no secret; short-lived access
+tokens refresh automatically.
+
+```sh
+frappectl auth login https://erp.example.com
+frappectl auth login https://erp.example.com --client-id <public-client-id>
+```
+
+Sites with dynamic client registration create the client automatically. Frappe v15+
+supports this by default; other sites need a pre-registered public `--client-id`.
+
+OAuth needs a terminal and local browser, so it isn't the headless path. Use `--oauth`
+to skip the authentication-method prompt.
+
+### Read-only profiles
+
+A read-only profile refuses every unsafe HTTP method **before the request leaves your
+machine**. This removes the obvious production footgun: an exploratory command can't
+accidentally mutate the site.
+
+```sh
+frappectl auth login https://prod.example.com --name prod --read-only
+frappectl auth configure prod --read-only             # lock an existing profile
+frappectl auth configure prod --writable              # allow writes again
+```
+
+This blocks `doc create/update/delete/submit`, `file upload`, and method calls through
+`api`/`method`. Reads such as `doc list/get`, `doctype show`, and `report run` keep
+working.
+
+For environment-variable auth, set `FRAPPE_READ_ONLY=1`. To invoke a whitelisted read
+method, make the safe verb explicit: `frappectl api method/… -X GET`.
+
+## Output and scripting
+
+- TTY → rich tables, colours and confirmation prompts.
+- Pipe or `--json` → clean JSON on stdout. Logs and errors stay on stderr, so piping to
+  `jq` is safe.
+- Mutations → refuse to run non-interactively without `--yes`.
+- Exit codes → `0` success, `1` failure, `2` usage error.
+- `--debug` → traces method, URL and headers to stderr. Credentials are redacted. For
+  endpoints that expose it, such as `doc list`, it also prints server-side SQL.
+
+Server error detail is plain text; HTML is stripped. `--debug` never touches stdout, so
+it won't corrupt `--json` output.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `frappectl doc list <DocType>` | List documents. Supports `-f`, `--fields`, `--limit` and `--all`. |
+| `frappectl doc get <DocType> <name>` | Fetch one document. |
+| `frappectl doc create <DocType>` | Create from `--set` scalars and/or piped/`--input` JSON. |
+| `frappectl doc update <DocType> <name>` | Update optimistically; use `--force` to override. |
+| `frappectl doc delete <DocType> <name>` | Delete after confirmation, or pass `--yes`. |
+| `frappectl doc submit\|cancel\|amend` | Run document lifecycle actions. |
+| `frappectl doctype list` / `frappectl doctype show <name>` | Discover doctypes and schema. |
+| `frappectl report run <name>` | Run a report with the same filter syntax as `doc list`. |
+| `frappectl file upload\|download` | Transfer files; upload supports `--doctype/--name` and `--private`. |
+| `frappectl api <path>` | Call raw v2 APIs: `frappectl api method/<path> -F key=value`. |
+| `frappectl guide` | Print the agent primer; no site or authentication needed. |
+| `frappectl assistant [pi\|claude\|codex]` | Launch a coding agent configured as a Frappe assistant. |
+| `frappectl update` | Self-upgrade through the `uv`/`pip` backend used for installation. |
+
+### Filtering
+
+Simple filters use `-f`. Repeat the flag to combine them:
+
+```sh
+frappectl doc list ToDo -f status=Open -f priority=High
+frappectl doc list "Sales Invoice" -f 'grand_total>1000' -f 'customer like %Inc%'
+```
+
+For `in`, `between`, child-table filters or anything else that doesn't fit cleanly in a
+shell argument, pass full Frappe filter JSON:
+
+```sh
+frappectl doc list "Sales Invoice" --filters-json '[["status","in",["Paid","Overdue"]]]'
+```
+
+## License
+
+MIT