nextcloud

Files (2)

• SKILL.md
• nextcloud.py · scripts/

SKILL.md (first lines)

# Nextcloud

One entry point for any Nextcloud instance:
`scripts/nextcloud.py`. It talks WebDAV for files and the OCS sharing API for
public link shares, and never invents a URL.

## Purpose

- Read files: `ls`, `cat`, `get`, `stat`, `info`.
- Write files: `put`, `set`, `append`, `mkdir`.
- Remove / reorganise: `rm` (recursive), `mv`.
- Public link shares: `share-create`, `share-list`, `share-update`,
  `share-delete`.

Standard library only — `python3 scripts/nextcloud.py --help` works with zero
setup.

## Setup

Credentials resolve in this order:

1. Environment variables `NC_URL` (full WebDAV root ending in
   `.../dav/files/<user>/`), `NC_USER`, `NC_PASS`.
2. Otherwise the `[nextcloud]` section of `~/.config/rclone/rclone.conf`
   (`url`, `user`, `pass`), confirmed as `type = webdav` / `vendor = nextcloud`.

Note: rclone stores `pass` *obscured* (AES-256-CTR with a fixed key), not
plaintext. The script decrypts it using the same scheme rclone uses
(`fs/config/obscure`), so a plain rclone.conf works as-is. `NC_PASS`, when
used, is taken verbatim.

The WebDAV mount at `~/Nextcloud` exists but this script does not use it — it
reaches WebDAV/OCS over HTTPS directly, so it works whether or not the mount
is up.

## Commands

| Command | Purpose |
| --- | --- |
| `ls [remote]` | PROPFIND Depth:1; one line per entry `D`/`F`, name, size (`-` for dirs), ISO mtime. Default `/`. |
| `cat <remote>` | GET, decode UTF-8, print to stdout. |
| `get <remote> [-o FILE]` | GET; stdout without `-o`, local file with `-o`. |
| `download <remote> <local>` | GET to a local path (creates parent dirs). |
| `stat <remote>` | PROPFIND Depth:0; name, type, size, mtime, etag, content-type. |
| `info` | `status.php` version/product, plus an authenticated PROPFIND check. |
| `put <local> <remote>` | PUT local bytes (overwrite); `local` `-` reads stdin. |
| `set <remote> --file/--stdin/--text` | Replace content entirely (PUT). |
| `append <remote> --text/--stdin/--file` | GET, append, PUT back (text files). |
| `rm <remote>` | DELETE (Nextcloud removes folders recursively). |
| `mv <src> <dst>` | MOVE with a `Destination:` header. |
| `mkdir <remote>` | MKCOL. |
| `share-create <remote> [--password P] [--expire YYYY-MM-DD] [--note N] [--name NAME] [--perm PERM]` | Create a public link share. |
| `share-list [remote]` | List public link shares (share_type 3). |
| `share-update <id> [--password P] [--clear-password] [--expire D] [--clear-expire] [--note N] [--perm PERM]` | Change share fields. |
| `share-delete <id>` | DELETE `/shares/{id}`. |

All remote paths are relative to the WebDAV root; a leading `/` is optional.
Each path segment is URL-encoded when building the request URL.

```sh
S=scripts/nextcloud.py

# list, read, fetch
python3 $S ls /
python3 $S cat notes/todo.md
python3 $S get report.pdf -o ./report.pdf
python3 $S stat photos/team.jpg

# write, edit, move, delete
python3 $S put ./logo.png assets/logo.png
printf 'line 1\n' | python3 $S set notes/todo.md --stdin
python3 $S append notes/todo.md --text $'\nline 2'
python3 $S mkdir archive/2026
python3 $S mv notes/todo.md archive/2026/todo.md
python3 $S rm archive/2026        # recursive

# share links
python3 $S share-create docs/report.pdf --password 'correct horse battery'
python3 $S share-list
python3 $S share-update 42 --note 'review draft' --perm download
python3 $S share-delete 42
```

Every command prints one short summary line on success, or `Error: <msg>` on
stderr with exit 1. Failures quote the first line of the server error body
when useful; auth failures read
`Error: HTTP 401 Unauthorized — check credentials in ~/.config/rclone/rclone.conf`.
Invalid flags exit 2 (argparse).

## Share-link semantics

Public link shares use `shareType = 3` over OCS. Permissions (`--perm`):

| Name | Value | Meaning |
| --- | --- | --- |
| `read` | 1 | Read-only (default) |
| `upload` | 15 | Upload + edit (file drop) |
| `download` | 19 | Read + download |

`share-create` prints the public URL (from the response `url`, falling back to
`{origin}/s/{token}`), the share id, token, and password-protected flag.
`--password` protects the link (Nextcloud requires ≥10 chars and rejects
compromised passwords); `--expire` sets an expiry date. `share-update` uses
`--clear-password` / `--clear-expire` to remove those fields.

Observed quirks (Nextcloud 33.0.3):

- The returned `permissions` includes the SHARE bit, so `read` reports `17`,
  `upload` `31`, `download` `35` — the input values are 1/15/19.
- The response `url` uses `http://`, not `https://`, and `password` is a
  non-null hash when a password is set (so `password-protected` is
  `bool(password)`).
- OCS needs `?format=json`; without it the body is XML.
- OCS rate-limits share creation to roughly one per ~10s; a burst of
  `share-create` calls returns 429. The script retries transient failures
  (timeouts, 5xx, 429, Cloudflare's `1010` challenge) with a short backoff,
  and 429 with a ~10s backoff.

## Rules

From VariableThe/agent-kit-public, MIT.

More from VariableThe/agent-kit-public