## nextcloud-bulk-users-utils (PyPI: ncbulk)
CLI: `nextcloud-bulk` · Python >= 3.12
### Why
- Bulk create/update Nextcloud users from CSV via the OCS Provisioning API.
Bulk creation and updates of Nextcloud users via the OCS Provisioning API.
### Features
- Create users from CSV.
- Group list in a single CSV field (`groups` or `group`), multiple groups separated by a configurable delimiter.
- Default quota and language via CLI/TUI or per-row via `quota` and `language` columns.
- Welcome mode (no password) – sends a welcome email (requires user email).
- Update existing users: email, displayname, quota, and add to groups.
- Dry-run, verbose logging, timeouts and retries.
- Flexible input/output CSV paths and delimiters.
- Step-by-step terminal wizard: delimiter auto-detection and CSV preview.
### Environment
Set admin credentials via environment variables (see `example.env`):
```bash
export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_ADMIN_USERNAME="admin"
export NEXTCLOUD_ADMIN_PASSWORD="secret"
```
You may put them into a local `.env` file; the tool reads values from the environment. An example file is provided as `example.env`.
Security note: `.env` may contain plaintext password and is git-ignored. Keep it local and protected.
Tip: Prefer using an App Password
For better security and least-privilege access, create an App Password in Nextcloud for the admin account and use it as `NEXTCLOUD_ADMIN_PASSWORD` instead of the main account password. If the tool reports 401/403 during the early OCS check, verify the credentials and consider switching to an App Password.
### CSV Format
CSV must include a header. Minimal columns: `username;email;displayname;group`
Optional columns: `groups` (instead of `group`), `quota`, `language`.
Default delimiter is `;` (you can change it). Example:
```text
username;email;displayname;groups;quota;language
alice;alice@example.org;Alice A;Students,Math;10GB;en
```
If present, `address` column is ignored.
### Install
Requires Python >= 3.12.
Local install:
```bash
pip install .
```
Via pipx (recommended isolation):
```bash
pipx install .
```
From PyPI:
```bash
pip install ncbulk
```
### Usage
Run the interactive step-by-step wizard:
```bash
# installed entry point (recommended)
nextcloud-bulk
# or run module directly (development)
python -m ncbulk.main
```
Run the CLI directly:
```bash
nextcloud-bulk --input list.csv --quota 10GB --language en --output users_passwds.csv
```
Key options:
- `--quota 10GB` – default quota (overridden by row `quota`).
- `--language en` – default language (overridden by row `language`).
- `--delimiter ";"` – CSV delimiter.
- `--groups-delimiter ","` – delimiter inside the groups field.
- `--welcome` – do not set password, send welcome email.
- `--password-length 12` – generated password length (when not in welcome mode).
- `--dry-run` – simulate without changes.
- `--verbose` – verbose HTTP attempts.
- `--timeout 15` – HTTP timeout in seconds.
- `--retries 2` – retry attempts.
- `--update-existing` – update existing users.
- `--input`, `--output` – input and report CSV paths.
### Output Report
The report file (default `users_passwds.csv`) has the columns:
```text
Username;Email;Displayname;Groups;Password;Status
```
Password is empty when `--welcome` is used. `Status` is one of `Created`, `Updated`, `Skipped`.
### Examples
1) Basic creation with default quota and language:
```bash
nextcloud-bulk --input list.csv --quota 10GB --language en
```
2) Multiple groups and per-row quota/language from CSV:
```text
username;email;displayname;groups;quota;language
bob;bob@example.org;Bob B;HR,Onboarding;5GB;en
```
```bash
nextcloud-bulk --input list.csv
```
3) Welcome mode and update existing users:
```bash
nextcloud-bulk --input list.csv --welcome --update-existing
```
4) Dry-run:
```bash
nextcloud-bulk --input list.csv --dry-run --verbose
```
### API Notes
- Create: `POST /ocs/v2.php/cloud/users` – params: `userid`, optional `password`, repeated `groups[]`, optional `language`.
- Update fields: `PUT /ocs/v2.php/cloud/users/{userid}` with `key`/`value` for `email`, `displayname`, `quota`, etc.
Docs: [Nextcloud User provisioning API](https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/instruction_set_for_users.html)
### Wizard
- Clear, step-by-step terminal prompts with validation at each step.
- Auto-detects CSV delimiter and shows a small preview.
- You can still run the CLI directly via `nextcloud-bulk`.
### License
Apache-2.0 © 2025 Jaguar Kovalev
Raw data
{
"_id": null,
"home_page": null,
"name": "ncbulk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "nextcloud, provisioning, ocs, csv, users, cli",
"author": "Jaguar Kovalev",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7e/d7/3223133a0ac2ba4bef3ccfa3810d893b41f30bb4c2cf739d918d25f41ee6/ncbulk-0.1.6.tar.gz",
"platform": null,
"description": "## nextcloud-bulk-users-utils (PyPI: ncbulk)\n\nCLI: `nextcloud-bulk` \u00b7 Python >= 3.12\n\n### Why\n- Bulk create/update Nextcloud users from CSV via the OCS Provisioning API.\n\n\nBulk creation and updates of Nextcloud users via the OCS Provisioning API.\n\n### Features\n- Create users from CSV.\n- Group list in a single CSV field (`groups` or `group`), multiple groups separated by a configurable delimiter.\n- Default quota and language via CLI/TUI or per-row via `quota` and `language` columns.\n- Welcome mode (no password) \u2013 sends a welcome email (requires user email).\n- Update existing users: email, displayname, quota, and add to groups.\n- Dry-run, verbose logging, timeouts and retries.\n- Flexible input/output CSV paths and delimiters.\n- Step-by-step terminal wizard: delimiter auto-detection and CSV preview.\n\n### Environment\nSet admin credentials via environment variables (see `example.env`):\n\n```bash\nexport NEXTCLOUD_URL=\"https://cloud.example.com\"\nexport NEXTCLOUD_ADMIN_USERNAME=\"admin\"\nexport NEXTCLOUD_ADMIN_PASSWORD=\"secret\"\n```\n\nYou may put them into a local `.env` file; the tool reads values from the environment. An example file is provided as `example.env`.\nSecurity note: `.env` may contain plaintext password and is git-ignored. Keep it local and protected.\n\nTip: Prefer using an App Password\n\nFor better security and least-privilege access, create an App Password in Nextcloud for the admin account and use it as `NEXTCLOUD_ADMIN_PASSWORD` instead of the main account password. If the tool reports 401/403 during the early OCS check, verify the credentials and consider switching to an App Password.\n\n### CSV Format\nCSV must include a header. Minimal columns: `username;email;displayname;group`\n\nOptional columns: `groups` (instead of `group`), `quota`, `language`.\n\nDefault delimiter is `;` (you can change it). Example:\n\n```text\nusername;email;displayname;groups;quota;language\nalice;alice@example.org;Alice A;Students,Math;10GB;en\n```\n\nIf present, `address` column is ignored.\n\n### Install\n\nRequires Python >= 3.12.\n\nLocal install:\n\n```bash\npip install .\n```\n\nVia pipx (recommended isolation):\n\n```bash\npipx install .\n```\n\nFrom PyPI:\n\n```bash\npip install ncbulk\n```\n\n### Usage\n\nRun the interactive step-by-step wizard:\n\n```bash\n# installed entry point (recommended)\nnextcloud-bulk\n\n# or run module directly (development)\npython -m ncbulk.main\n```\n\nRun the CLI directly:\n\n```bash\nnextcloud-bulk --input list.csv --quota 10GB --language en --output users_passwds.csv\n```\n\nKey options:\n- `--quota 10GB` \u2013 default quota (overridden by row `quota`).\n- `--language en` \u2013 default language (overridden by row `language`).\n- `--delimiter \";\"` \u2013 CSV delimiter.\n- `--groups-delimiter \",\"` \u2013 delimiter inside the groups field.\n- `--welcome` \u2013 do not set password, send welcome email.\n- `--password-length 12` \u2013 generated password length (when not in welcome mode).\n- `--dry-run` \u2013 simulate without changes.\n- `--verbose` \u2013 verbose HTTP attempts.\n- `--timeout 15` \u2013 HTTP timeout in seconds.\n- `--retries 2` \u2013 retry attempts.\n- `--update-existing` \u2013 update existing users.\n- `--input`, `--output` \u2013 input and report CSV paths.\n\n### Output Report\nThe report file (default `users_passwds.csv`) has the columns:\n\n```text\nUsername;Email;Displayname;Groups;Password;Status\n```\n\nPassword is empty when `--welcome` is used. `Status` is one of `Created`, `Updated`, `Skipped`.\n\n### Examples\n\n1) Basic creation with default quota and language:\n```bash\nnextcloud-bulk --input list.csv --quota 10GB --language en\n```\n\n2) Multiple groups and per-row quota/language from CSV:\n```text\nusername;email;displayname;groups;quota;language\nbob;bob@example.org;Bob B;HR,Onboarding;5GB;en\n```\n```bash\nnextcloud-bulk --input list.csv\n```\n\n3) Welcome mode and update existing users:\n```bash\nnextcloud-bulk --input list.csv --welcome --update-existing\n```\n\n4) Dry-run:\n```bash\nnextcloud-bulk --input list.csv --dry-run --verbose\n```\n\n### API Notes\n- Create: `POST /ocs/v2.php/cloud/users` \u2013 params: `userid`, optional `password`, repeated `groups[]`, optional `language`.\n- Update fields: `PUT /ocs/v2.php/cloud/users/{userid}` with `key`/`value` for `email`, `displayname`, `quota`, etc.\n\nDocs: [Nextcloud User provisioning API](https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/instruction_set_for_users.html)\n\n### Wizard\n- Clear, step-by-step terminal prompts with validation at each step.\n- Auto-detects CSV delimiter and shows a small preview.\n- You can still run the CLI directly via `nextcloud-bulk`.\n\n### License\nApache-2.0 \u00a9 2025 Jaguar Kovalev\n",
"bugtrack_url": null,
"license": null,
"summary": "Nextcloud bulk user creation and update tool with CLI/TUI",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/JaguarKovalev/nextcloud-bulk-users",
"Issues": "https://github.com/JaguarKovalev/nextcloud-bulk-users/issues"
},
"split_keywords": [
"nextcloud",
" provisioning",
" ocs",
" csv",
" users",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be2e42d2d8f8be9728880f9593beba769a89f40da9c818e8603a6be32265f0b2",
"md5": "7e773ecb99858ef714780b2292508896",
"sha256": "9e2eebe647c8a449da886dbcfae26e1bc2b8a8f6608176768df8cd404d820e79"
},
"downloads": -1,
"filename": "ncbulk-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e773ecb99858ef714780b2292508896",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 16555,
"upload_time": "2025-10-13T11:47:54",
"upload_time_iso_8601": "2025-10-13T11:47:54.376651Z",
"url": "https://files.pythonhosted.org/packages/be/2e/42d2d8f8be9728880f9593beba769a89f40da9c818e8603a6be32265f0b2/ncbulk-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7ed73223133a0ac2ba4bef3ccfa3810d893b41f30bb4c2cf739d918d25f41ee6",
"md5": "cc8e471e8219d487e20c36a1dcb78337",
"sha256": "b1bd73ab4e658822aa69915b8d31e8e9a72528fa47d12c68862ac2bb890037cc"
},
"downloads": -1,
"filename": "ncbulk-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "cc8e471e8219d487e20c36a1dcb78337",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 16495,
"upload_time": "2025-10-13T11:47:55",
"upload_time_iso_8601": "2025-10-13T11:47:55.398516Z",
"url": "https://files.pythonhosted.org/packages/7e/d7/3223133a0ac2ba4bef3ccfa3810d893b41f30bb4c2cf739d918d25f41ee6/ncbulk-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-13 11:47:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JaguarKovalev",
"github_project": "nextcloud-bulk-users",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ncbulk"
}
JSON
