{"id":51055790,"url":"https://github.com/chenasraf/nextcloud-deck-tools","last_synced_at":"2026-06-22T21:01:10.067Z","repository":{"id":330373431,"uuid":"1055137681","full_name":"chenasraf/nextcloud-deck-tools","owner":"chenasraf","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-30T21:06:32.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-26T00:29:13.533Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chenasraf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T20:30:43.000Z","updated_at":"2026-04-30T21:06:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chenasraf/nextcloud-deck-tools","commit_stats":null,"previous_names":["chenasraf/nextcloud-deck-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chenasraf/nextcloud-deck-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenasraf%2Fnextcloud-deck-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenasraf%2Fnextcloud-deck-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenasraf%2Fnextcloud-deck-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenasraf%2Fnextcloud-deck-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chenasraf","download_url":"https://codeload.github.com/chenasraf/nextcloud-deck-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenasraf%2Fnextcloud-deck-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34665261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-22T21:01:09.087Z","updated_at":"2026-06-22T21:01:10.060Z","avatar_url":"https://github.com/chenasraf.png","language":"Python","funding_links":["https://ko-fi.com/casraf'"],"categories":[],"sub_categories":[],"readme":"# Nextcloud Deck Tools\n\nA collection of Python tools for interacting with Nextcloud Deck via its API. Features a unified\ninteractive CSV importer and standalone utilities for board and stack management.\n\n## Features\n\n- **Interactive CSV Importer** - Unified tool with guided workflow for importing tasks\n- **Board Management** - Create and list boards\n- **Stack Management** - Create and list stacks/columns\n- **CSV Import** - Batch import tasks from CSV files\n- **Flexible Authentication** - Support for environment variables, CLI arguments, and interactive\n  prompts\n- **Both Interactive \u0026 Non-Interactive Modes** - Choose your workflow\n\n## Installation\n\nThis project uses Poetry for dependency management.\n\n```bash\n# Install dependencies\npoetry install\n\n# Or if you already have poetry.lock\npoetry install --no-root\n```\n\n## Quick Start\n\n### Interactive Mode (Recommended)\n\nRun the unified interactive tool:\n\n```bash\nmake\n# or\npoetry run python main.py\n```\n\nThis will guide you through:\n\n1. Selecting or creating a board\n2. Choosing which column/stack to import to\n3. Selecting a CSV file\n4. Confirming and importing\n\n### Non-Interactive Mode\n\nIf you already know your board ID, stack ID, and CSV file:\n\n```bash\npoetry run python main.py \\\n  --domain https://cloud.example.com \\\n  --board-id 5 \\\n  --stack-id 12 \\\n  --csv-file tasks.csv\n```\n\nOr use environment variables (see below) and run without arguments.\n\n## Environment Variables\n\nThe tools support multiple environment variable formats for convenience:\n\n### Authentication \u0026 Connection\n\n- `NEXTCLOUD_DOMAIN` or `NEXTCLOUD_BASE_URL` - Your Nextcloud instance URL\n- `NEXTCLOUD_USERNAME` or `NC_USERNAME` - Username\n- `NEXTCLOUD_PASSWORD` or `NC_PASSWORD` - Password or app password\n\n### Board \u0026 Stack IDs\n\n- `NEXTCLOUD_BOARD_ID` or `BOARD_ID` - Board ID for operations\n- `NEXTCLOUD_STACK_ID` or `STACK_ID` - Stack/column ID for import\n- `NEXTCLOUD_BOARD_NAME` or `BOARD_NAME` - Board name when creating\n\n### Import Configuration\n\n- `IMPORT_CSV_FILE` or `CSV_FILE` - Path to CSV file\n- `NEW_BOARD_COLUMNS` - Comma-separated list of column names for new boards\n  - Example: `NEW_BOARD_COLUMNS=\"Backlog,To Do,In Progress,Review,Done\"`\n  - If not set, uses defaults: \"🐞 Bugs,📋 To Do,🔄 In Progress,✅ Done,📄 Backlog\"\n\n### Setting Up Environment Variables\n\nCopy `.env.example` to `.env` and fill in your values:\n\n```bash\nexport NEXTCLOUD_DOMAIN=\"https://cloud.example.com\"\nexport NEXTCLOUD_USERNAME=\"your-username\"\nexport NEXTCLOUD_PASSWORD=\"your-app-password\"\nexport NEW_BOARD_COLUMNS=\"Backlog,To Do,In Progress,Done\"\n```\n\n## CSV File Format\n\nCSV files should have the following format:\n\n```csv\ntitle,description\n\"Task Title\",\"Task description with **markdown** support\"\n\"Another Task\",\"Description can be multi-line and supports markdown\"\n```\n\n**Requirements:**\n\n- Header row with `title` and `description` columns\n- Title is required (rows without title are skipped)\n- Description is optional\n- Markdown formatting is supported in descriptions\n\n## Individual Scripts\n\nWhile `main.py` provides a unified workflow, you can still use individual scripts.\n\nIn each script, the `.env` file may be used in place of the respective CLI arguments.\n\n### List Boards\n\n```bash\nmake list_boards\n# or\npoetry run python list_boards.py\n```\n\n**Options:**\n\n- `--domain` - Nextcloud instance URL\n- `--username` - Username\n- `--password` - Password\n- `--json` - Output raw JSON instead of table\n\n### Create Board\n\n```bash\nmake create_board\n# or\npoetry run python create_board.py\n```\n\n**Options:**\n\n- `--domain` - Nextcloud instance URL\n- `--username` - Username\n- `--password` - Password\n- `--board-name` - Name for the new board\n- `--no-default-stacks` - Skip creating default stacks/columns\n\n**Environment Variables:**\n\n- Uses `NEW_BOARD_COLUMNS` if set, otherwise creates default stacks\n\n### List Stacks\n\n```bash\nmake list_stacks\n# or\npoetry run python list_stacks.py\n```\n\n**Options:**\n\n- `--domain` - Nextcloud instance URL\n- `--board-id` - Board ID to list stacks from\n- `--username` - Username\n- `--password` - Password\n- `--json` - Output raw JSON instead of table\n\n### Import CSV\n\n```bash\nmake import\n# or\npoetry run python import.py\n```\n\n**Options:**\n\n- `--domain` - Nextcloud instance URL\n- `--board-id` - Target board ID\n- `--stack-id` - Target stack/column ID\n- `--username` - Username\n- `--password` - Password\n- `--csv-file` - Path to CSV file\n\n## Usage Examples\n\n### Example 1: Complete Interactive Workflow\n\n```bash\n# Set up authentication once\nexport NEXTCLOUD_DOMAIN=\"https://cloud.example.com\"\nexport NEXTCLOUD_USERNAME=\"john\"\nexport NEXTCLOUD_PASSWORD=\"app-password-here\"\n\n# Run interactive importer\nmake all\n```\n\nThe tool will:\n\n1. Show existing boards and option to create new one\n2. If creating new, prompt for name and use `NEW_BOARD_COLUMNS`\n3. Show columns in selected/created board\n4. List CSV files in current directory\n5. Confirm and import\n\n### Example 2: Automated Import with Environment Variables\n\n```bash\nexport NEXTCLOUD_DOMAIN=\"https://cloud.example.com\"\nexport NEXTCLOUD_USERNAME=\"john\"\nexport NEXTCLOUD_PASSWORD=\"app-password\"\nexport BOARD_ID=\"5\"\nexport STACK_ID=\"12\"\nexport CSV_FILE=\"tasks.csv\"\n\n# Runs non-interactively\npoetry run python main.py\n```\n\n### Example 3: Create Board with Custom Columns\n\n```bash\nexport NEXTCLOUD_DOMAIN=\"https://cloud.example.com\"\nexport NEXTCLOUD_USERNAME=\"john\"\nexport NEXTCLOUD_PASSWORD=\"app-password\"\nexport NEW_BOARD_COLUMNS=\"📥 Inbox,🎯 Today,📅 This Week,✅ Done,📦 Archive\"\n\npoetry run python create_board.py --board-name \"My Project\"\n```\n\n### Example 4: Quick Board Listing\n\n```bash\npoetry run python list_boards.py \\\n  --domain https://cloud.example.com \\\n  --username john\n# Will prompt for password securely\n```\n\n### Example 5: Import with All CLI Arguments\n\n```bash\npoetry run python main.py \\\n  --domain https://cloud.example.com \\\n  --username john \\\n  --password app-password \\\n  --board-id 5 \\\n  --stack-id 12 \\\n  --csv-file ./tasks/project-tasks.csv\n```\n\n## Project Structure\n\n```\nnextcloud-deck-tools/\n├── main.py              # Unified interactive CSV importer\n├── create_board.py      # Create boards with stacks\n├── list_boards.py       # List all boards\n├── list_stacks.py       # List stacks for a board\n├── import.py            # Import CSV to specific stack\n├── common.py            # Shared utilities and functions\n├── Makefile             # Task shortcuts\n├── pyproject.toml       # Poetry dependencies\n└── README.md            # This file\n```\n\n## Makefile Targets\n\n- `make all` - Run the unified interactive importer (default)\n- `make create_board` - Create a new board\n- `make list_boards` - List all boards\n- `make list_stacks` - List stacks for a board\n- `make import` - Import CSV to a stack\n\n## Authentication\n\nFor security, it's recommended to use Nextcloud **app passwords** instead of your main account\npassword:\n\n1. Go to Nextcloud Settings → Security\n2. Create a new app password\n3. Use that password in `NEXTCLOUD_PASSWORD` or `--password`\n\nPasswords can be:\n\n- Set in environment variables (convenient but less secure)\n- Passed via CLI arguments (visible in shell history)\n- Entered interactively when prompted (most secure, uses hidden input)\n\n## Resolution Priority\n\nWhen multiple input methods are available, the tools use this priority:\n\n1. **Environment variables** - Checked first\n2. **CLI arguments** - Override environment variables\n3. **Interactive prompts** - Final fallback if nothing else provided\n\nThis allows flexible workflows: set common values in ENV, override specific values with CLI args, or\nuse fully interactive mode.\n\n## Requirements\n\n- Python 3.11+\n- Poetry\n- Nextcloud instance with Deck app installed\n- Valid Nextcloud account credentials\n\n## Dependencies\n\n- `requests` - HTTP client for API calls\n- `inquirer` - Interactive CLI prompts (for main.py)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## Contributing\n\nI am developing this package on my free time, so any support, whether code, issues, or just stars is\nvery helpful to sustaining its life. If you are feeling incredibly generous and would like to donate\njust a small amount to help sustain this project, I would be very very thankful!\n\n\u003ca href='https://ko-fi.com/casraf' target='_blank'\u003e\n  \u003cimg height='36' style='border:0px;height:36px;'\n    src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3'\n    alt='Buy Me a Coffee at ko-fi.com' /\u003e\n\u003c/a\u003e\n\nI welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature,\ndon't hesitate to open an appropriate issue and I will do my best to reply promptly.\n\n## Tips\n\n- Use `--json` flag with list commands to pipe output to `jq` or other tools\n- Store credentials in `.envrc` and use `direnv` for automatic loading\n- Create different `.envrc` files for different Nextcloud instances\n- CSV files support markdown in descriptions - great for formatted task details\n- All scripts support `--help` for detailed usage information\n\n## Troubleshooting\n\n**Authentication fails:**\n\n- Verify your Nextcloud URL includes the protocol (`https://`)\n- Check that your username/password are correct\n- Consider using an app password instead of account password\n\n**Board/Stack not found:**\n\n- Use `list_boards.py` and `list_stacks.py` to find correct IDs\n- Board and stack IDs are integers, not names\n\n**CSV import skips rows:**\n\n- Ensure CSV has `title` and `description` header row\n- Check that titles are not empty\n- Verify file encoding is UTF-8\n\n**Interactive mode not working:**\n\n- Ensure `inquirer` is installed: `poetry install`\n- Check terminal supports interactive input (some CI environments don't)\n- Try non-interactive mode with full CLI arguments instead\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenasraf%2Fnextcloud-deck-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchenasraf%2Fnextcloud-deck-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenasraf%2Fnextcloud-deck-tools/lists"}