cospend-cli

cospend-cli is a command-line interface for managing expenses in Nextcloud Cospend projects. It provides a quick way to add and list expenses directly from your terminal without opening the web interface.

---

Features

• Add, list, and delete expenses in Cospend projects via the REST API
• List projects you have access to
• Filter expenses by payer, owed members, amount, name, category, payment method, or date
• Resolve categories, payment methods, and members by name or ID
• Case-insensitive matching for all lookups
• Currency code support (e.g., usd, eur, gbp) with automatic symbol resolution
• Local caching of project data with 1-hour TTL for faster subsequent calls
• Global project flag - set -p before the command for easy shell aliases
• Secure browser login - OAuth-style authentication with 2FA support
• Cross-platform support: macOS, Linux, and Windows

---

Installation

Download Precompiled Binaries

Precompiled binaries for cospend-cli are available for Linux, macOS, and Windows:

• Visit the Releases Page to download the latest version for your platform.

Homebrew (macOS/Linux)

brew install chenasraf/tap/cospend-cli

Build from Source

go install github.com/chenasraf/cospend-cli@latest

---

Configuration

Quick Setup (Recommended)

Run the interactive setup wizard:

cospend init

This will prompt for your Nextcloud domain and let you choose an authentication method using an interactive selector (use arrow keys or j/k to navigate, Enter to select):

Choose login method:
  > Browser login (recommended) - Opens browser for secure authentication
    Password/App token - Enter credentials manually

• Browser login (recommended) - Opens your browser for secure OAuth-style authentication. Handles 2FA automatically and generates an app-specific password.

• Password/App token - Enter your credentials manually (useful for headless servers).

You can specify the config format with --format:

cospend init --format yaml
cospend init --format toml
cospend init --format json  # default

Config File

The config file is searched in the following locations (in order of preference):

OS	Primary Location	Fallback Location
Linux	~/.config/cospend/cospend.{json,yaml,toml}	-
macOS	~/Library/Application Support/cospend/cospend.*	~/.config/cospend/cospend.{json,yaml,toml}
Windows	%APPDATA%\cospend\cospend.*	-

Example config files:

{
  "domain": "https://cloud.example.com",
  "user": "alice",
  "password": "your-app-password"
}

domain: https://cloud.example.com
user: alice
password: your-app-password

domain = "https://cloud.example.com"
user = "alice"
password = "your-app-password"

Environment Variables

You can also use environment variables, which override config file values:

Variable	Description
NEXTCLOUD_DOMAIN	Your Nextcloud instance URL
NEXTCLOUD_USER	Your Nextcloud username
NEXTCLOUD_PASSWORD	Your Nextcloud password or app token

export NEXTCLOUD_DOMAIN="https://cloud.example.com"
export NEXTCLOUD_USER="alice"
export NEXTCLOUD_PASSWORD="your-app-password"

Tip: For security, consider using a Nextcloud app password instead of your main password.

---

Usage

Global Flags

The -p/--project flag can be used before or after the command, making it easy to create shell aliases:

# These are equivalent:
cospend add "Groceries" 25.50 -p myproject
cospend -p myproject add "Groceries" 25.50

# Create an alias for a specific project:
alias cospend-home="cospend -p homeproject"
cospend-home add "Groceries" 25.50
cospend-home list

---

Adding Expenses

cospend add <name> <amount> [flags]

Examples

# Add a simple expense
cospend add "Groceries" 25.50 -p myproject

# Add an expense with category and split between members
cospend add "Dinner" 45.00 -p myproject -c restaurant -f alice -f bob

# Add an expense paid by someone else
cospend add "Gas" 60.00 -p roadtrip -b charlie -f alice -f bob -f charlie

# Add an expense with payment method and comment
cospend add "Hotel" 150.00 -p vacation -m "credit card" -o "2 nights"

# Add an expense in a different currency
cospend add "Souvenirs" 30.00 -p vacation -C usd

# Add an expense with a specific date
cospend add "Lunch" 15.00 -p myproject -d 2026-03-15
cospend add "Lunch" 15.00 -p myproject -d 03-15        # assumes current year
cospend add "Lunch" 15.00 -p myproject -d -1d          # yesterday
cospend add "Lunch" 15.00 -p myproject -d +2d          # 2 days from now

Add Command Flags

Short	Long	Description
-p	--project	Project ID (required)
-c	--category	Category by ID or case-insensitive name
-b	--by	Paying member username (defaults to authenticated user)
-f	--for	Owed member username (repeatable; defaults to payer only)
-C	--convert	Currency to convert to (by ID, name, or code like usd)
-m	--method	Payment method by ID or case-insensitive name
-o	--comment	Additional details about the bill
-d	--date	Date of expense (YYYY-MM-DD, MM-DD, or relative like -1d, +2w)
-h	--help	Display help information

---

Listing Expenses

cospend list [flags]
cospend ls [flags]    # alias

Examples

# List all expenses in a project
cospend list -p myproject

# Filter by paying member
cospend list -p myproject -b alice

# Filter by category
cospend list -p myproject -c groceries

# Filter by amount (supports =, >, <, >=, <=)
cospend list -p myproject --amount ">50"
cospend list -p myproject --amount "<=100"

# Filter by name (case-insensitive, contains)
cospend list -p myproject -n dinner

# Filter by date (supports =, >, <, >=, <=)
cospend list -p myproject --date ">=2026-01-01"
cospend list -p myproject --date "<=01-15"        # short MM-DD format (assumes current year)

# Filter by today, current month, or week
cospend list -p myproject --today
cospend list -p myproject --this-month
cospend list -p myproject --this-week

# Filter recent bills (d=days, w=weeks, m=months)
cospend list -p myproject --recent 7d
cospend list -p myproject --recent 2w
cospend list -p myproject --recent 1m

# Combine multiple filters
cospend list -p myproject -b alice -c restaurant --amount ">=20"

# Output as CSV or JSON
cospend list -p myproject --format csv
cospend list -p myproject --format json

List Command Flags

Short	Long	Description
-p	--project	Project ID (required)
-b	--by	Filter by paying member username
-f	--for	Filter by owed member username (repeatable)
-a	--amount	Filter by amount (e.g., 50, >30, <=100, =25)
-n	--name	Filter by name (case-insensitive, contains)
-c	--category	Filter by category name or ID
-m	--method	Filter by payment method name or ID
-l	--limit	Limit number of results (0 = no limit)
-d	--date	Filter by date (e.g., 2026-01-15, >=2026-01-01, <=01-15)
	--today	Filter bills from today
	--this-month	Filter bills from the current month
	--this-week	Filter bills from the current calendar week
	--recent	Filter recent bills (e.g., 7d, 2w, 1m)
	--format	Output format: table (default), csv, json
-h	--help	Display help information

The output includes the bill ID for each expense, which can be used with the delete command.

---

Deleting Expenses

cospend delete <bill_id> [flags]
cospend rm <bill_id> [flags]      # alias

Examples

# Delete a bill by ID (use 'cospend list' to find bill IDs)
cospend delete 123 -p myproject

Delete Command Flags

Short	Long	Description
-p	--project	Project ID (required)
-h	--help	Display help information

---

Listing Projects

cospend projects [flags]
cospend proj [flags]    # alias

Examples

# List all active projects
cospend projects

# Include archived projects
cospend projects --all

Projects Command Flags

Short	Long	Description
-a	--all	Show all projects including archived
-h	--help	Display help information

---

Caching

Project data (members, categories, payment methods, currencies) is cached locally to avoid repeated API calls. The cache is stored in:

OS	Location
Linux	~/.cache/cospend-cli/
macOS	~/Library/Caches/cospend-cli/
Windows	%LOCALAPPDATA%\cospend-cli\

Cache entries expire after 1 hour. To force a refresh, simply delete the cache file for your project.

---

Currency Codes

When using the -C flag, you can specify currencies by:

1. Numeric ID - The Cospend currency ID
2. Name - The currency name as configured in Cospend (case-insensitive)
3. Currency code - Standard codes like usd, eur, gbp, jpy, etc.

Currency codes are automatically mapped to their symbols (e.g., usd -> $, eur -> €) and matched against your project’s configured currencies.

---

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!

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.

---

License

cospend-cli is licensed under the MIT License.