nextcloud-cli 0.1.0__tar.gz

nextcloud_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types:
+      - created
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Github actions init
+        uses: actions/checkout@v6
+        with:
+          # To force fetching tags
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@v1.13.0

nextcloud_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Github actions init
+        uses: actions/checkout@v6
+        with:
+          # To force fetching tags
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build
+        run: python -m build
+
+      - name: Read VERSION file
+        id: getversion
+        run: echo "version=$(cat src/nextcloud_cli/VERSION.md)" >> $GITHUB_OUTPUT
+
+      - name: Changelog
+        run: git log $(git describe --tags --abbrev=0)..HEAD --format="%s %h" > LATEST-CHANGES.md
+
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/nextcloud_cli-${{ steps.getversion.outputs.version }}-py3-none-any.whl
+            dist/nextcloud_cli-${{ steps.getversion.outputs.version }}.tar.gz
+          tag_name: v${{ steps.getversion.outputs.version }}
+          body_path: LATEST-CHANGES.md
+          token: ${{ secrets.PAT_NXCLOUD }}

nextcloud_cli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+env/
+.env
+.env.local
+.idea/
+.vscode/
+*.swp
+.DS_Store

nextcloud_cli-0.1.0/LICENSE

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

nextcloud_cli-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: nextcloud-cli
+Version: 0.1.0
+Summary: Modern command-line client for Nextcloud (files, notes, calendar, tasks, contacts)
+Project-URL: Homepage, https://github.com/AlexMili/nextcloud-cli
+Project-URL: Issues, https://github.com/AlexMili/nextcloud-cli/issues
+Project-URL: Source, https://github.com/AlexMili/nextcloud-cli
+Author: AlexMili
+License-File: LICENSE
+Keywords: caldav,carddav,cli,nextcloud,webdav
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: caldav>=1.3
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: icalendar>=5.0
+Requires-Dist: keyring>=24.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: rich>=13.0
+Requires-Dist: tzlocal>=5.0
+Requires-Dist: vobject>=0.9.7
+Requires-Dist: webdav4>=0.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nextcloud-cli
+
+`nxcloud` is a modern command-line client for self-hosted Nextcloud. Manage
+files, notes, calendar events, tasks, and contacts from the terminal — over
+HTTPS only, no desktop sync client required.
+
+It speaks WebDAV via [`webdav4`](https://pypi.org/project/webdav4/), CalDAV
+via [`caldav`](https://pypi.org/project/caldav/), CardDAV via raw `httpx` +
+[`vobject`](https://pypi.org/project/vobject/), and the Nextcloud Notes REST
+API via `httpx`. Credentials are stored in your OS keyring.
+
+## Features
+
+- **Files** — list, upload, download, move, delete, mkdir, recursive search
+- **Notes** — create, read, update, delete (Nextcloud Notes app required)
+- **Calendar** — list calendars, list/create/edit/delete events, **with attendees and organizer**
+- **Tasks** — list/create/complete/edit/delete VTODO items
+- **Contacts** — list address books, list/get/export vCards
+- **Login wizard** that validates the credentials with a `PROPFIND` and stores the password in the OS keyring (with a `chmod 0600` JSON fallback)
+- **JSON output everywhere** so you can pipe into `jq` and friends
+- `-h` / `--help` available on every command and subcommand
+
+## Installation
+
+```bash
+pip install nextcloud-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/AlexMili/nextcloud-cli
+cd nextcloud-cli
+pip install -e .
+```
+
+The installed binary is **`nxcloud`**.
+
+## Login
+
+Create a Nextcloud **app password** first
+(`Settings → Security → App passwords`), then:
+
+```bash
+nxcloud login
+```
+
+You'll only be prompted for what's missing. Values are resolved in this order:
+
+1. CLI flag (`--url`, `--username`, `--password`, `--timezone`)
+2. Environment variable (`NEXTCLOUD_URL`, `NEXTCLOUD_USER`, `NEXTCLOUD_TOKEN`, `NEXTCLOUD_TIMEZONE`)
+3. Interactive prompt
+
+So all of these work:
+
+```bash
+# Fully interactive
+nxcloud login
+
+# Mixed: URL from env, prompt for the rest
+NEXTCLOUD_URL=https://nc.example.com nxcloud login
+
+# Fully non-interactive (no prompts)
+nxcloud login \
+    --url https://nc.example.com \
+    --username alice \
+    --password 'app-pass-here' \
+    --timezone Europe/Paris
+```
+
+You can also skip persistence entirely and rely on environment variables for
+every command:
+
+```bash
+export NEXTCLOUD_URL=https://nc.example.com
+export NEXTCLOUD_USER=alice
+export NEXTCLOUD_TOKEN=app-pass-here
+export NEXTCLOUD_TIMEZONE=Europe/Paris
+nxcloud check
+```
+
+To remove stored credentials:
+
+```bash
+nxcloud logout
+```
+
+## Usage
+
+Every command emits JSON on stdout for easy scripting. Use `-h` on any
+command or subcommand for built-in help.
+
+### Connectivity check
+
+```bash
+nxcloud check
+```
+
+### Files
+
+```bash
+nxcloud files list --path /Documents
+nxcloud files upload --local ./report.pdf --remote /Documents/report.pdf
+nxcloud files download --remote /Documents/report.pdf --local ./report.pdf
+nxcloud files move --src /tmp/a.txt --dst /archive/a.txt
+nxcloud files mkdir --path /new-folder
+nxcloud files delete --path /old.txt
+nxcloud files search --query report --limit 20    # OCS unified search (server-side)
+```
+
+### Notes (requires the Nextcloud Notes app)
+
+```bash
+nxcloud notes list
+nxcloud notes list --category Work              # notes in the "Work" folder
+nxcloud notes list --category "Work/Projects"   # nested folder (subdirectory)
+nxcloud notes list --category=""                # only notes at the Notes/ root (no category)
+nxcloud notes list --limit 10                   # cap the number of notes fetched
+nxcloud notes get --id 941
+nxcloud notes create --title "Meeting" --content "Q3 roadmap." --category Work
+nxcloud notes edit --id 941 --title "Updated"
+nxcloud notes delete --id 941
+```
+
+> In the Nextcloud Notes app, **category = folder**: notes are stored as
+> Markdown files under `Notes/<category>/`, and `/` separates subdirectories.
+> `--category` matches **exactly** — `--category Work` does not include
+> `Work/Projects`. Use `--category=""` to list only notes at the root.
+
+### Calendar
+
+List calendars and events:
+
+```bash
+nxcloud calendar list
+nxcloud calendar events --calendar Personal --start 2026-05-01 --end 2026-05-31
+```
+
+Date-range shortcuts (server-side filtering, in your configured timezone):
+
+```bash
+nxcloud calendar events --calendar Personal --today
+nxcloud calendar events --calendar Personal --this-week     # current Mon → Mon
+nxcloud calendar events --calendar Personal --next-week     # upcoming Mon → Mon
+nxcloud calendar events --calendar Personal --this-month    # 1st → 1st of next month
+nxcloud calendar events --calendar Personal --next-month
+nxcloud calendar events --calendar Personal --next 7d       # also: 48h, 2w
+```
+
+> Shortcuts are mutually exclusive with each other and with `--start/--end`.
+
+Create an event with attendees and an organizer:
+
+```bash
+nxcloud calendar create \
+    --calendar Work \
+    --summary "Project sync" \
+    --start 2026-07-01T14:00:00 \
+    --end   2026-07-01T15:00:00 \
+    --location "Room 4B" \
+    --description "Quarterly review" \
+    --organizer "Alice <alice@example.com>" \
+    --attendee "Bob <bob@example.com>" \
+    --attendee carol@example.com
+```
+
+`--attendee` is repeatable and accepts either a bare email or the
+`Name <email>` form.
+
+Edit an event (including adding/removing invitees):
+
+```bash
+nxcloud calendar edit --calendar Work --uid <uid> --summary "New title"
+nxcloud calendar edit --calendar Work --uid <uid> \
+    --add-attendee "Dan <dan@example.com>" \
+    --remove-attendee carol@example.com
+```
+
+Delete an event:
+
+```bash
+nxcloud calendar delete --calendar Work --uid <uid>
+```
+
+Search events server-side (CalDAV `text-match`). Combine with date filters:
+
+```bash
+nxcloud calendar search --calendar Work --query standup
+nxcloud calendar search --calendar Work --query roadmap --in description
+nxcloud calendar search --calendar Work --query "1:1" --this-week
+# --in: summary | description | location | category | all  (default: summary)
+```
+
+### Tasks (VTODO)
+
+```bash
+nxcloud tasks list
+nxcloud tasks list --include-completed
+nxcloud tasks create --summary "Review PR" --due 2026-07-05 --priority 1
+nxcloud tasks complete --uid <uid>
+nxcloud tasks edit --uid <uid> --summary "Updated summary"
+nxcloud tasks delete --uid <uid>
+nxcloud tasks search --query "deploy" --include-completed
+nxcloud tasks search --query "fix" --in description --list Work
+# --in: summary | description | category | all  (default: summary)
+```
+
+### Contacts
+
+```bash
+nxcloud contacts list
+nxcloud contacts cards --addressbook contacts
+nxcloud contacts get --addressbook contacts --uid <uid>
+nxcloud contacts export --addressbook contacts --uid <uid> --local ./alice.vcf
+nxcloud contacts search --addressbook contacts --query alex
+nxcloud contacts search --addressbook contacts --query "@example.com" --in email
+# --in: name | email | phone | all  (default: all)
+```
+
+## Configuration files
+
+| File | Purpose | Permissions |
+|------|---------|-------------|
+| `~/.config/nextcloud-cli/config.json` | URL, username, timezone | `0600` |
+| OS keyring (entry `nextcloud-cli`) | App password | OS-managed |
+| `~/.config/nextcloud-cli/secrets.json` | Password fallback when no keyring backend is available | `0600` |
+
+Override the config directory with the `NEXTCLOUD_CLI_HOME` environment variable.
+
+## Help
+
+`-h` and `--help` are wired up at every level:
+
+```bash
+nxcloud --help
+nxcloud calendar --help
+nxcloud calendar create --help
+```
+
+## License
+
+MIT

nextcloud_cli-0.1.0/README.md

@@ -0,0 +1,242 @@
+# nextcloud-cli
+
+`nxcloud` is a modern command-line client for self-hosted Nextcloud. Manage
+files, notes, calendar events, tasks, and contacts from the terminal — over
+HTTPS only, no desktop sync client required.
+
+It speaks WebDAV via [`webdav4`](https://pypi.org/project/webdav4/), CalDAV
+via [`caldav`](https://pypi.org/project/caldav/), CardDAV via raw `httpx` +
+[`vobject`](https://pypi.org/project/vobject/), and the Nextcloud Notes REST
+API via `httpx`. Credentials are stored in your OS keyring.
+
+## Features
+
+- **Files** — list, upload, download, move, delete, mkdir, recursive search
+- **Notes** — create, read, update, delete (Nextcloud Notes app required)
+- **Calendar** — list calendars, list/create/edit/delete events, **with attendees and organizer**
+- **Tasks** — list/create/complete/edit/delete VTODO items
+- **Contacts** — list address books, list/get/export vCards
+- **Login wizard** that validates the credentials with a `PROPFIND` and stores the password in the OS keyring (with a `chmod 0600` JSON fallback)
+- **JSON output everywhere** so you can pipe into `jq` and friends
+- `-h` / `--help` available on every command and subcommand
+
+## Installation
+
+```bash
+pip install nextcloud-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/AlexMili/nextcloud-cli
+cd nextcloud-cli
+pip install -e .
+```
+
+The installed binary is **`nxcloud`**.
+
+## Login
+
+Create a Nextcloud **app password** first
+(`Settings → Security → App passwords`), then:
+
+```bash
+nxcloud login
+```
+
+You'll only be prompted for what's missing. Values are resolved in this order:
+
+1. CLI flag (`--url`, `--username`, `--password`, `--timezone`)
+2. Environment variable (`NEXTCLOUD_URL`, `NEXTCLOUD_USER`, `NEXTCLOUD_TOKEN`, `NEXTCLOUD_TIMEZONE`)
+3. Interactive prompt
+
+So all of these work:
+
+```bash
+# Fully interactive
+nxcloud login
+
+# Mixed: URL from env, prompt for the rest
+NEXTCLOUD_URL=https://nc.example.com nxcloud login
+
+# Fully non-interactive (no prompts)
+nxcloud login \
+    --url https://nc.example.com \
+    --username alice \
+    --password 'app-pass-here' \
+    --timezone Europe/Paris
+```
+
+You can also skip persistence entirely and rely on environment variables for
+every command:
+
+```bash
+export NEXTCLOUD_URL=https://nc.example.com
+export NEXTCLOUD_USER=alice
+export NEXTCLOUD_TOKEN=app-pass-here
+export NEXTCLOUD_TIMEZONE=Europe/Paris
+nxcloud check
+```
+
+To remove stored credentials:
+
+```bash
+nxcloud logout
+```
+
+## Usage
+
+Every command emits JSON on stdout for easy scripting. Use `-h` on any
+command or subcommand for built-in help.
+
+### Connectivity check
+
+```bash
+nxcloud check
+```
+
+### Files
+
+```bash
+nxcloud files list --path /Documents
+nxcloud files upload --local ./report.pdf --remote /Documents/report.pdf
+nxcloud files download --remote /Documents/report.pdf --local ./report.pdf
+nxcloud files move --src /tmp/a.txt --dst /archive/a.txt
+nxcloud files mkdir --path /new-folder
+nxcloud files delete --path /old.txt
+nxcloud files search --query report --limit 20    # OCS unified search (server-side)
+```
+
+### Notes (requires the Nextcloud Notes app)
+
+```bash
+nxcloud notes list
+nxcloud notes list --category Work              # notes in the "Work" folder
+nxcloud notes list --category "Work/Projects"   # nested folder (subdirectory)
+nxcloud notes list --category=""                # only notes at the Notes/ root (no category)
+nxcloud notes list --limit 10                   # cap the number of notes fetched
+nxcloud notes get --id 941
+nxcloud notes create --title "Meeting" --content "Q3 roadmap." --category Work
+nxcloud notes edit --id 941 --title "Updated"
+nxcloud notes delete --id 941
+```
+
+> In the Nextcloud Notes app, **category = folder**: notes are stored as
+> Markdown files under `Notes/<category>/`, and `/` separates subdirectories.
+> `--category` matches **exactly** — `--category Work` does not include
+> `Work/Projects`. Use `--category=""` to list only notes at the root.
+
+### Calendar
+
+List calendars and events:
+
+```bash
+nxcloud calendar list
+nxcloud calendar events --calendar Personal --start 2026-05-01 --end 2026-05-31
+```
+
+Date-range shortcuts (server-side filtering, in your configured timezone):
+
+```bash
+nxcloud calendar events --calendar Personal --today
+nxcloud calendar events --calendar Personal --this-week     # current Mon → Mon
+nxcloud calendar events --calendar Personal --next-week     # upcoming Mon → Mon
+nxcloud calendar events --calendar Personal --this-month    # 1st → 1st of next month
+nxcloud calendar events --calendar Personal --next-month
+nxcloud calendar events --calendar Personal --next 7d       # also: 48h, 2w
+```
+
+> Shortcuts are mutually exclusive with each other and with `--start/--end`.
+
+Create an event with attendees and an organizer:
+
+```bash
+nxcloud calendar create \
+    --calendar Work \
+    --summary "Project sync" \
+    --start 2026-07-01T14:00:00 \
+    --end   2026-07-01T15:00:00 \
+    --location "Room 4B" \
+    --description "Quarterly review" \
+    --organizer "Alice <alice@example.com>" \
+    --attendee "Bob <bob@example.com>" \
+    --attendee carol@example.com
+```
+
+`--attendee` is repeatable and accepts either a bare email or the
+`Name <email>` form.
+
+Edit an event (including adding/removing invitees):
+
+```bash
+nxcloud calendar edit --calendar Work --uid <uid> --summary "New title"
+nxcloud calendar edit --calendar Work --uid <uid> \
+    --add-attendee "Dan <dan@example.com>" \
+    --remove-attendee carol@example.com
+```
+
+Delete an event:
+
+```bash
+nxcloud calendar delete --calendar Work --uid <uid>
+```
+
+Search events server-side (CalDAV `text-match`). Combine with date filters:
+
+```bash
+nxcloud calendar search --calendar Work --query standup
+nxcloud calendar search --calendar Work --query roadmap --in description
+nxcloud calendar search --calendar Work --query "1:1" --this-week
+# --in: summary | description | location | category | all  (default: summary)
+```
+
+### Tasks (VTODO)
+
+```bash
+nxcloud tasks list
+nxcloud tasks list --include-completed
+nxcloud tasks create --summary "Review PR" --due 2026-07-05 --priority 1
+nxcloud tasks complete --uid <uid>
+nxcloud tasks edit --uid <uid> --summary "Updated summary"
+nxcloud tasks delete --uid <uid>
+nxcloud tasks search --query "deploy" --include-completed
+nxcloud tasks search --query "fix" --in description --list Work
+# --in: summary | description | category | all  (default: summary)
+```
+
+### Contacts
+
+```bash
+nxcloud contacts list
+nxcloud contacts cards --addressbook contacts
+nxcloud contacts get --addressbook contacts --uid <uid>
+nxcloud contacts export --addressbook contacts --uid <uid> --local ./alice.vcf
+nxcloud contacts search --addressbook contacts --query alex
+nxcloud contacts search --addressbook contacts --query "@example.com" --in email
+# --in: name | email | phone | all  (default: all)
+```
+
+## Configuration files
+
+| File | Purpose | Permissions |
+|------|---------|-------------|
+| `~/.config/nextcloud-cli/config.json` | URL, username, timezone | `0600` |
+| OS keyring (entry `nextcloud-cli`) | App password | OS-managed |
+| `~/.config/nextcloud-cli/secrets.json` | Password fallback when no keyring backend is available | `0600` |
+
+Override the config directory with the `NEXTCLOUD_CLI_HOME` environment variable.
+
+## Help
+
+`-h` and `--help` are wired up at every level:
+
+```bash
+nxcloud --help
+nxcloud calendar --help
+nxcloud calendar create --help
+```
+
+## License
+
+MIT