mirror of
https://github.com/chenasraf/nextcloud-deck-tools.git
synced 2026-05-17 17:28:07 +00:00
docs: add README.md and LICENSE
This commit is contained in:
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright © 2025 Chen Asraf
|
||||
|
||||
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.
|
||||
365
README.md
Normal file
365
README.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Nextcloud Deck Tools
|
||||
|
||||
A collection of Python tools for interacting with Nextcloud Deck via its API. Features a unified
|
||||
interactive CSV importer and standalone utilities for board and stack management.
|
||||
|
||||
## Features
|
||||
|
||||
- **Interactive CSV Importer** - Unified tool with guided workflow for importing tasks
|
||||
- **Board Management** - Create and list boards
|
||||
- **Stack Management** - Create and list stacks/columns
|
||||
- **CSV Import** - Batch import tasks from CSV files
|
||||
- **Flexible Authentication** - Support for environment variables, CLI arguments, and interactive
|
||||
prompts
|
||||
- **Both Interactive & Non-Interactive Modes** - Choose your workflow
|
||||
|
||||
## Installation
|
||||
|
||||
This project uses Poetry for dependency management.
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
poetry install
|
||||
|
||||
# Or if you already have poetry.lock
|
||||
poetry install --no-root
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Interactive Mode (Recommended)
|
||||
|
||||
Run the unified interactive tool:
|
||||
|
||||
```bash
|
||||
make
|
||||
# or
|
||||
poetry run python main.py
|
||||
```
|
||||
|
||||
This will guide you through:
|
||||
|
||||
1. Selecting or creating a board
|
||||
2. Choosing which column/stack to import to
|
||||
3. Selecting a CSV file
|
||||
4. Confirming and importing
|
||||
|
||||
### Non-Interactive Mode
|
||||
|
||||
If you already know your board ID, stack ID, and CSV file:
|
||||
|
||||
```bash
|
||||
poetry run python main.py \
|
||||
--domain https://cloud.example.com \
|
||||
--board-id 5 \
|
||||
--stack-id 12 \
|
||||
--csv-file tasks.csv
|
||||
```
|
||||
|
||||
Or use environment variables (see below) and run without arguments.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The tools support multiple environment variable formats for convenience:
|
||||
|
||||
### Authentication & Connection
|
||||
|
||||
- `NEXTCLOUD_DOMAIN` or `NEXTCLOUD_BASE_URL` - Your Nextcloud instance URL
|
||||
- `NEXTCLOUD_USERNAME` or `NC_USERNAME` - Username
|
||||
- `NEXTCLOUD_PASSWORD` or `NC_PASSWORD` - Password or app password
|
||||
|
||||
### Board & Stack IDs
|
||||
|
||||
- `NEXTCLOUD_BOARD_ID` or `BOARD_ID` - Board ID for operations
|
||||
- `NEXTCLOUD_STACK_ID` or `STACK_ID` - Stack/column ID for import
|
||||
- `NEXTCLOUD_BOARD_NAME` or `BOARD_NAME` - Board name when creating
|
||||
|
||||
### Import Configuration
|
||||
|
||||
- `IMPORT_CSV_FILE` or `CSV_FILE` - Path to CSV file
|
||||
- `NEW_BOARD_COLUMNS` - Comma-separated list of column names for new boards
|
||||
- Example: `NEW_BOARD_COLUMNS="Backlog,To Do,In Progress,Review,Done"`
|
||||
- If not set, uses defaults: "🐞 Bugs,📋 To Do,🔄 In Progress,✅ Done,📄 Backlog"
|
||||
|
||||
### Setting Up Environment Variables
|
||||
|
||||
Copy `.env.example` to `.env` and fill in your values:
|
||||
|
||||
```bash
|
||||
export NEXTCLOUD_DOMAIN="https://cloud.example.com"
|
||||
export NEXTCLOUD_USERNAME="your-username"
|
||||
export NEXTCLOUD_PASSWORD="your-app-password"
|
||||
export NEW_BOARD_COLUMNS="Backlog,To Do,In Progress,Done"
|
||||
```
|
||||
|
||||
## CSV File Format
|
||||
|
||||
CSV files should have the following format:
|
||||
|
||||
```csv
|
||||
title,description
|
||||
"Task Title","Task description with **markdown** support"
|
||||
"Another Task","Description can be multi-line and supports markdown"
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
|
||||
- Header row with `title` and `description` columns
|
||||
- Title is required (rows without title are skipped)
|
||||
- Description is optional
|
||||
- Markdown formatting is supported in descriptions
|
||||
|
||||
## Individual Scripts
|
||||
|
||||
While `main.py` provides a unified workflow, you can still use individual scripts.
|
||||
|
||||
In each script, the `.env` file may be used in place of the respective CLI arguments.
|
||||
|
||||
### List Boards
|
||||
|
||||
```bash
|
||||
make list_boards
|
||||
# or
|
||||
poetry run python list_boards.py
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--domain` - Nextcloud instance URL
|
||||
- `--username` - Username
|
||||
- `--password` - Password
|
||||
- `--json` - Output raw JSON instead of table
|
||||
|
||||
### Create Board
|
||||
|
||||
```bash
|
||||
make create_board
|
||||
# or
|
||||
poetry run python create_board.py
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--domain` - Nextcloud instance URL
|
||||
- `--username` - Username
|
||||
- `--password` - Password
|
||||
- `--board-name` - Name for the new board
|
||||
- `--no-default-stacks` - Skip creating default stacks/columns
|
||||
|
||||
**Environment Variables:**
|
||||
|
||||
- Uses `NEW_BOARD_COLUMNS` if set, otherwise creates default stacks
|
||||
|
||||
### List Stacks
|
||||
|
||||
```bash
|
||||
make list_stacks
|
||||
# or
|
||||
poetry run python list_stacks.py
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--domain` - Nextcloud instance URL
|
||||
- `--board-id` - Board ID to list stacks from
|
||||
- `--username` - Username
|
||||
- `--password` - Password
|
||||
- `--json` - Output raw JSON instead of table
|
||||
|
||||
### Import CSV
|
||||
|
||||
```bash
|
||||
make import
|
||||
# or
|
||||
poetry run python import.py
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--domain` - Nextcloud instance URL
|
||||
- `--board-id` - Target board ID
|
||||
- `--stack-id` - Target stack/column ID
|
||||
- `--username` - Username
|
||||
- `--password` - Password
|
||||
- `--csv-file` - Path to CSV file
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Complete Interactive Workflow
|
||||
|
||||
```bash
|
||||
# Set up authentication once
|
||||
export NEXTCLOUD_DOMAIN="https://cloud.example.com"
|
||||
export NEXTCLOUD_USERNAME="john"
|
||||
export NEXTCLOUD_PASSWORD="app-password-here"
|
||||
|
||||
# Run interactive importer
|
||||
make all
|
||||
```
|
||||
|
||||
The tool will:
|
||||
|
||||
1. Show existing boards and option to create new one
|
||||
2. If creating new, prompt for name and use `NEW_BOARD_COLUMNS`
|
||||
3. Show columns in selected/created board
|
||||
4. List CSV files in current directory
|
||||
5. Confirm and import
|
||||
|
||||
### Example 2: Automated Import with Environment Variables
|
||||
|
||||
```bash
|
||||
export NEXTCLOUD_DOMAIN="https://cloud.example.com"
|
||||
export NEXTCLOUD_USERNAME="john"
|
||||
export NEXTCLOUD_PASSWORD="app-password"
|
||||
export BOARD_ID="5"
|
||||
export STACK_ID="12"
|
||||
export CSV_FILE="tasks.csv"
|
||||
|
||||
# Runs non-interactively
|
||||
poetry run python main.py
|
||||
```
|
||||
|
||||
### Example 3: Create Board with Custom Columns
|
||||
|
||||
```bash
|
||||
export NEXTCLOUD_DOMAIN="https://cloud.example.com"
|
||||
export NEXTCLOUD_USERNAME="john"
|
||||
export NEXTCLOUD_PASSWORD="app-password"
|
||||
export NEW_BOARD_COLUMNS="📥 Inbox,🎯 Today,📅 This Week,✅ Done,📦 Archive"
|
||||
|
||||
poetry run python create_board.py --board-name "My Project"
|
||||
```
|
||||
|
||||
### Example 4: Quick Board Listing
|
||||
|
||||
```bash
|
||||
poetry run python list_boards.py \
|
||||
--domain https://cloud.example.com \
|
||||
--username john
|
||||
# Will prompt for password securely
|
||||
```
|
||||
|
||||
### Example 5: Import with All CLI Arguments
|
||||
|
||||
```bash
|
||||
poetry run python main.py \
|
||||
--domain https://cloud.example.com \
|
||||
--username john \
|
||||
--password app-password \
|
||||
--board-id 5 \
|
||||
--stack-id 12 \
|
||||
--csv-file ./tasks/project-tasks.csv
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
nextcloud-deck-tools/
|
||||
├── main.py # Unified interactive CSV importer
|
||||
├── create_board.py # Create boards with stacks
|
||||
├── list_boards.py # List all boards
|
||||
├── list_stacks.py # List stacks for a board
|
||||
├── import.py # Import CSV to specific stack
|
||||
├── common.py # Shared utilities and functions
|
||||
├── Makefile # Task shortcuts
|
||||
├── pyproject.toml # Poetry dependencies
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Makefile Targets
|
||||
|
||||
- `make all` - Run the unified interactive importer (default)
|
||||
- `make create_board` - Create a new board
|
||||
- `make list_boards` - List all boards
|
||||
- `make list_stacks` - List stacks for a board
|
||||
- `make import` - Import CSV to a stack
|
||||
|
||||
## Authentication
|
||||
|
||||
For security, it's recommended to use Nextcloud **app passwords** instead of your main account
|
||||
password:
|
||||
|
||||
1. Go to Nextcloud Settings → Security
|
||||
2. Create a new app password
|
||||
3. Use that password in `NEXTCLOUD_PASSWORD` or `--password`
|
||||
|
||||
Passwords can be:
|
||||
|
||||
- Set in environment variables (convenient but less secure)
|
||||
- Passed via CLI arguments (visible in shell history)
|
||||
- Entered interactively when prompted (most secure, uses hidden input)
|
||||
|
||||
## Resolution Priority
|
||||
|
||||
When multiple input methods are available, the tools use this priority:
|
||||
|
||||
1. **Environment variables** - Checked first
|
||||
2. **CLI arguments** - Override environment variables
|
||||
3. **Interactive prompts** - Final fallback if nothing else provided
|
||||
|
||||
This allows flexible workflows: set common values in ENV, override specific values with CLI args, or
|
||||
use fully interactive mode.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.11+
|
||||
- Poetry
|
||||
- Nextcloud instance with Deck app installed
|
||||
- Valid Nextcloud account credentials
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `requests` - HTTP client for API calls
|
||||
- `inquirer` - Interactive CLI prompts (for main.py)
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
|
||||
## Contributing
|
||||
|
||||
I am developing this package on my free time, so any support, whether code, issues, or just stars is
|
||||
very helpful to sustaining its life. If you are feeling incredibly generous and would like to donate
|
||||
just a small amount to help sustain this project, I would be very very thankful!
|
||||
|
||||
<a href='https://ko-fi.com/casraf' target='_blank'>
|
||||
<img height='36' style='border:0px;height:36px;'
|
||||
src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3'
|
||||
alt='Buy Me a Coffee at ko-fi.com' />
|
||||
</a>
|
||||
|
||||
I welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature,
|
||||
don't hesitate to open an appropriate issue and I will do my best to reply promptly.
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `--json` flag with list commands to pipe output to `jq` or other tools
|
||||
- Store credentials in `.envrc` and use `direnv` for automatic loading
|
||||
- Create different `.envrc` files for different Nextcloud instances
|
||||
- CSV files support markdown in descriptions - great for formatted task details
|
||||
- All scripts support `--help` for detailed usage information
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Authentication fails:**
|
||||
|
||||
- Verify your Nextcloud URL includes the protocol (`https://`)
|
||||
- Check that your username/password are correct
|
||||
- Consider using an app password instead of account password
|
||||
|
||||
**Board/Stack not found:**
|
||||
|
||||
- Use `list_boards.py` and `list_stacks.py` to find correct IDs
|
||||
- Board and stack IDs are integers, not names
|
||||
|
||||
**CSV import skips rows:**
|
||||
|
||||
- Ensure CSV has `title` and `description` header row
|
||||
- Check that titles are not empty
|
||||
- Verify file encoding is UTF-8
|
||||
|
||||
**Interactive mode not working:**
|
||||
|
||||
- Ensure `inquirer` is installed: `poetry install`
|
||||
- Check terminal supports interactive input (some CI environments don't)
|
||||
- Try non-interactive mode with full CLI arguments instead
|
||||
Reference in New Issue
Block a user