https://github.com/michaeloboyle/copilot-cli
CLI tool for querying Copilot.money data via CSV exports
https://github.com/michaeloboyle/copilot-cli
Last synced: 3 months ago
JSON representation
CLI tool for querying Copilot.money data via CSV exports
- Host: GitHub
- URL: https://github.com/michaeloboyle/copilot-cli
- Owner: michaeloboyle
- License: other
- Created: 2025-11-22T14:31:07.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T21:16:52.000Z (4 months ago)
- Last Synced: 2026-05-05T18:49:19.162Z (3 months ago)
- Language: TypeScript
- Size: 168 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# copilot-cli
CLI tool for querying [Copilot.money](https://copilot.money) financial data via CSV exports.
## Installation
```bash
npm install
npm run build
npm link # Makes 'copilot' command available globally
```
## Example Output
```
$ copilot tx -d 7
┌────────────┬────────────────────────────────────────┬────────────────────┬────────────┐
│ Date │ Description │ Category │ Amount │
├────────────┼────────────────────────────────────────┼────────────────────┼────────────┤
│ 2025-11-22 │ Whole Foods Market │ Groceries │ 87.43 │
│ 2025-11-21 │ Shell Gas Station │ Auto │ 45.00 │
│ 2025-11-21 │ Starbucks │ Restaurants │ 6.50 │
│ 2025-11-20 │ Amazon Prime │ Shopping │ 14.99 │
│ 2025-11-19 │ Netflix │ Entertainment │ 15.99 │
└────────────┴────────────────────────────────────────┴────────────────────┴────────────┘
```
```
$ copilot summary --by-category -d 30
Spending by Category (last 30 days)
┌─────────────────────────┬───────────────┬───────────────┐
│ Category │ Spent │ Transactions │
├─────────────────────────┼───────────────┼───────────────┤
│ Groceries │ 543.21 │ 12 │
│ Restaurants │ 287.50 │ 18 │
│ Auto │ 156.00 │ 4 │
│ Entertainment │ 45.99 │ 3 │
└─────────────────────────┴───────────────┴───────────────┘
```
## Usage
### Import transactions from CSV
```bash
# Import a CSV file manually exported from Copilot
copilot import ~/Downloads/copilot-export.csv
# Preview without importing
copilot import ~/Downloads/copilot-export.csv --dry-run
```
### Query transactions
```bash
# Last 30 days
copilot transactions
# Shortcuts
copilot tx -d 7 # Last 7 days
copilot tx -c groceries # Filter by category
copilot tx -s "amazon" # Search description
copilot tx --min -100 # Minimum amount
copilot tx --json # JSON output
```
### View summaries
```bash
# Overview of last 30 days
copilot summary
# Spending by category
copilot summary --by-category
# Monthly breakdown
copilot summary --by-month
# Custom period
copilot summary -d 90 --by-category
```
### Utility commands
```bash
copilot db-path # Show database location
```
## Data Storage
Data is stored in `~/.copilot-cli/copilot.db` (SQLite).
## Workflow
1. Export CSV from Copilot.money app (Settings → Account → Export)
2. Run `copilot import ~/Downloads/copilot-export.csv`
3. Query with `copilot tx` or `copilot summary`
Re-import anytime to add new transactions (duplicates are automatically skipped).
## FAQ / Troubleshooting
### "permission denied: copilot" after npm link
The TypeScript compiler doesn't preserve execute permissions. Fix with:
```bash
chmod +x $(npm prefix -g)/lib/node_modules/copilot-cli/dist/cli.js
```
Or rebuild (this runs automatically now):
```bash
npm run build # postbuild script sets +x
```
### Command not found after npm link
Your shell may not have the npm global bin in PATH. Check with:
```bash
echo $PATH | grep -o '[^:]*npm[^:]*'
npm prefix -g # Shows where npm installs global packages
```
Add to your shell config (~/.zshrc or ~/.bashrc):
```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```
### Import shows 0 transactions
Make sure you're exporting from Copilot.money, not another app. The CSV should have columns like: `date`, `name`, `amount`, `category`, `account`.
### Search returns no results
Searches look at the transaction description. Run `copilot tx -d 7` to see recent transactions and verify descriptions are populated.
### "SQLITE_CONSTRAINT" error on import
This can happen with corrupted or partial imports. Reset the database:
```bash
rm ~/.copilot-cli/copilot.db
copilot import your-file.csv
```
### How do I export from Copilot.money?
1. Open Copilot app on Mac/iPhone
2. Go to **Settings** → **Account** → **Export**
3. Choose date range and export as CSV
4. Import with `copilot import ~/Downloads/copilot-export.csv`
### Can I use this with other finance apps?
The CSV parser is flexible and handles common column names (date, description, amount, category, account). If your app exports similar CSV format, it may work. Test with `--dry-run` first.
### Where is my data stored?
```bash
copilot db-path # Shows: ~/.copilot-cli/copilot.db
```
This is a SQLite database. You can query it directly:
```bash
sqlite3 ~/.copilot-cli/copilot.db "SELECT COUNT(*) FROM transactions"
```
### How do I backup my data?
```bash
cp ~/.copilot-cli/copilot.db ~/copilot-backup-$(date +%Y%m%d).db
```
## Legal Disclaimers
### Not Financial Advice
This software is a data management tool only. Nothing in this software constitutes financial, investment, legal, or tax advice. The developers are not financial advisors, accountants, or attorneys. Always consult qualified professionals for financial decisions.
### No Affiliation
This project is **not affiliated with, endorsed by, or connected to**:
- **Copilot.money** or its parent company
- **Microsoft Corporation** or GitHub Copilot
- **Any other "Copilot" branded product or service**
"Copilot" in this project name refers solely to compatibility with CSV exports from the Copilot.money personal finance app. All trademarks belong to their respective owners.
### Data Accuracy
This software processes data you provide via CSV exports. The developers make no guarantees about:
- Accuracy of parsed data
- Completeness of imports
- Correctness of calculations or summaries
**You are responsible for verifying all financial data.** Do not rely on this tool for tax preparation, financial reporting, or legal compliance without independent verification.
### No Warranty
This software is provided "as is" without warranty of any kind. See the [LICENSE](LICENSE) file for complete terms.
### Security Notice
This tool stores your financial transaction data locally in an unencrypted SQLite database (`~/.copilot-cli/copilot.db`). You are responsible for:
- Securing access to your computer
- Backing up your data
- Protecting exported CSV files containing sensitive financial information
### Privacy
This tool operates entirely offline. No data is transmitted to external servers. Your financial data never leaves your machine.
## License
MIT License - see [LICENSE](LICENSE) for details.