nextcloud-cli 0.1.0__py3-none-any.whl

nextcloud_cli/utils.py

@@ -0,0 +1,129 @@
+"""Small helpers shared across command modules."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager, nullcontext
+from datetime import UTC, datetime
+from typing import Any, NoReturn
+
+import click
+from dateutil import parser as date_parser
+from rich.console import Console
+from rich.logging import RichHandler
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def configure_logging(verbosity: int) -> None:
+    """Configure stderr logging based on a -v / -vv counter.
+
+    - 0: WARNING (default — silent on success)
+    - 1: INFO    (one line per HTTP request)
+    - 2+: DEBUG  (full request/response headers via httpx)
+    """
+    if verbosity <= 0:
+        level = logging.WARNING
+    elif verbosity == 1:
+        level = logging.INFO
+    else:
+        level = logging.DEBUG
+
+    handler: logging.Handler
+    if err_console.is_terminal:
+        handler = RichHandler(
+            console=err_console,
+            show_path=False,
+            markup=False,
+            rich_tracebacks=True,
+            log_time_format="[%X]",
+        )
+        fmt = "%(name)s: %(message)s"
+    else:
+        handler = logging.StreamHandler(sys.stderr)
+        fmt = "%(asctime)s %(levelname)s %(name)s: %(message)s"
+    handler.setFormatter(logging.Formatter(fmt))
+    logging.basicConfig(level=level, handlers=[handler], force=True)
+    if verbosity < 2:
+        logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+
+def _verbose_callback(ctx: click.Context, param: click.Parameter, value: int) -> int:
+    if value:
+        configure_logging(value)
+    return value
+
+
+verbose_option = click.option(
+    "-v",
+    "--verbose",
+    count=True,
+    expose_value=False,
+    is_eager=True,
+    callback=_verbose_callback,
+    help="Increase log verbosity (-v: HTTP requests, -vv: full headers).",
+)
+
+json_option = click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    default=False,
+    help="Emit raw JSON to stdout (machine-readable, no spinner, no colors).",
+)
+
+
+def parse_datetime(value: str, default_tz: str = "UTC") -> datetime:
+    """Parse an ISO 8601 string into an aware datetime."""
+    dt = date_parser.isoparse(value)
+    if dt.tzinfo is None:
+        try:
+            from zoneinfo import ZoneInfo
+
+            dt = dt.replace(tzinfo=ZoneInfo(default_tz))
+        except Exception:
+            dt = dt.replace(tzinfo=UTC)
+    return dt
+
+
+def format_size(num_bytes: int) -> str:
+    size = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024 or unit == "TB":
+            return f"{size:.1f} {unit}" if unit != "B" else f"{int(size)} B"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+
+@contextmanager
+def spinner(message: str, json_output: bool = False) -> Iterator[None]:
+    """Show a Rich spinner on stderr while a block runs.
+
+    Suppressed in --json mode and when stderr is not a TTY (CI logs stay clean).
+    """
+    if json_output or not err_console.is_terminal:
+        with nullcontext():
+            yield
+        return
+    with err_console.status(f"[bold cyan]{message}[/bold cyan]", spinner="dots"):
+        yield
+
+
+def emit(payload: Any) -> None:
+    """Print JSON to stdout. Used in --json mode and as a fallback."""
+    json.dump(payload, sys.stdout, indent=2, default=str, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def fail(message: str, code: int = 1) -> NoReturn:
+    if err_console.is_terminal:
+        err_console.print(f"[bold red]error:[/bold red] {message}")
+    else:
+        sys.stderr.write(f"error: {message}\n")
+    sys.exit(code)

nextcloud_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+nextcloud_cli/VERSION.md,sha256=atlhOkVXmNbZLl9fOQq0uqcFlryGntaxf1zdKyhjXwY,5
+nextcloud_cli/__init__.py,sha256=Uk7Cw4n-7jFgEGpixZL9VSOUspcLOvLv76HxxbnWAVc,71
+nextcloud_cli/__main__.py,sha256=XCMQvGDl8AgHJwA5Q5xk2YUVnrKhgS0Oaf9MtW0p-gg,74
+nextcloud_cli/cli.py,sha256=bnVKzg-z6wX94iVJjUsQ3PwNbyOCwhFw-P0zkZ_oX7s,985
+nextcloud_cli/client.py,sha256=4utyvj6__GpR4jPthgk2Ps599U0OeR7p8O25Eqep24A,1241
+nextcloud_cli/config.py,sha256=iCqF-YEnvZhfNI6K0JdoZ_eIYqmfQ42_dgQ4cOM02YM,4544
+nextcloud_cli/rendering.py,sha256=tJvULiTE81mdwspyCQIhgwMAlw9tMhljEdYK8qVTTWw,9751
+nextcloud_cli/utils.py,sha256=NwTmN9p_UGFvErM6qLJnpAvR9l1vRVZOTijXXyM_ysE,3689
+nextcloud_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nextcloud_cli/commands/calendar.py,sha256=NLXSNxeSThpYtJDR9Flwdt3BR4o15pKt0oHrcUYyWuQ,15769
+nextcloud_cli/commands/check.py,sha256=11BGhR6Q3i0BFcIcLqfRexmLBVtnyFuuIsmI2Jshvjs,2480
+nextcloud_cli/commands/contacts.py,sha256=hvLt4PLwNhA_am6TpsSgoBSDPzzjMtKKsgynI66h-yA,9014
+nextcloud_cli/commands/files.py,sha256=Rh0x83m3e7POZeJbWbDOP_kIAhagbnIQ-MX6XNsDzQs,5740
+nextcloud_cli/commands/notes.py,sha256=G-tGE-Nyi3ZoIkPiQdehcezSxE97tDDf7W0LtfFWTvE,4370
+nextcloud_cli/commands/setup.py,sha256=kNH_5bQHZbR1w9YBRQ0SFhzkL8McBZyTsooExOhWYcg,2658
+nextcloud_cli/commands/tasks.py,sha256=ha47kpJ2InkS_jT0mTNDpdg7qahZ4Y1iqB9ytb16Q5g,8528
+nextcloud_cli-0.1.0.dist-info/METADATA,sha256=nCvZrztoQsXKYRsMEoxO-XrqDwCym791Wt08lBm416w,8928
+nextcloud_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nextcloud_cli-0.1.0.dist-info/entry_points.txt,sha256=fmuw7wYIkiG9hJRo8ScqGbCePp0vSreWlsA73SZitHg,51
+nextcloud_cli-0.1.0.dist-info/licenses/LICENSE,sha256=M5XFEFVqTKWMabj00jE2NKZen6Ri6fFdh9NMOiBV0AQ,1066
+nextcloud_cli-0.1.0.dist-info/RECORD,,

nextcloud_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nextcloud_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nxcloud = nextcloud_cli.cli:main

nextcloud_cli-0.1.0.dist-info/licenses/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.