A collection of CLI tools for freelancers: time tracking exports, invoice generation, bank statement imports, tax estimation, and document management.
harvest-exporter - Export timesheets from Harvest with currency conversion via Wise exchange rates
- Homepage: https://getharvest.com
- Usage:
nix run github:numtide/freelancer-toolbox#harvest-exporter -- --help - Nix: nix/packages/harvest-exporter.nix
- Documentation: packages/harvest/src/harvest_exporter/README.md
kimai-exporter - Export time entries from Kimai with currency conversion
- Homepage: https://www.kimai.org
- Usage:
nix run github:numtide/freelancer-toolbox#kimai-exporter -- --help - Nix: nix/packages/kimai-exporter.nix
- Documentation: packages/kimai/src/kimai_exporter/README.md
harvest-rounder - Round Harvest time entries up to the nearest billing increment
- Homepage: https://getharvest.com
- Usage:
nix run github:numtide/freelancer-toolbox#harvest-rounder -- --help - Nix: nix/packages/harvest-rounder.nix
- Documentation: packages/harvest/src/harvest_rounder/README.md
working-days-calculator - Calculate working days from a Harvest annual CSV export
Export the annual CSV from numtide.harvestapp.com/reports?kind=year, then:
working-days-calculator annual-report.csv- Usage:
nix run github:numtide/freelancer-toolbox#working-days-calculator -- <csv_file> - Nix: nix/packages/working-days-calculator.nix
harvest-invoicer - Fetch Harvest time data, edit line items in a local browser, and generate PDF invoices
- Usage:
nix run github:numtide/freelancer-toolbox#harvest-invoicer -- serve(interactive editor) or... generate --month YYYY-MM(headless) - Nix: nix/packages/harvest-invoicer.nix
- Documentation: packages/harvest-invoicer/README.md
sevdesk-invoicer - SevDesk integration: invoice generation, Wise bank imports, and German tax estimation
This package exposes three commands:
-
sevdesk-invoicer— generate SevDesk invoices from harvest-exporter or kimai-exporter JSON output -
sevdesk-wise-importer— import Wise bank transactions into SevDesk check accounts -
sevdesk-tax-estimator— calculate remaining German tax payments -
Homepage: https://sevdesk.com
-
Usage:
nix run github:numtide/freelancer-toolbox#sevdesk-invoicer -- --help -
Documentation: packages/sevdesk-invoicer/README.md
sevdesk-cli - Command-line interface for the SevDesk API (vouchers, transactions, accounts)
The console script is named sevdesk.
- Homepage: https://sevdesk.com
- Usage:
nix run github:numtide/freelancer-toolbox#sevdesk-cli -- --help - Nix: nix/packages/sevdesk-cli.nix
- Documentation: packages/sevdesk-cli/README.md
quipu-invoicer - Generate invoices in Quipu from time tracking exports
This package exposes two commands:
-
quipu-invoicer— generate Quipu invoices from harvest-exporter or kimai-exporter JSON output -
quipu-cli— Python CLI for the Quipu API -
Homepage: https://getquipu.com
-
Usage:
nix run github:numtide/freelancer-toolbox#quipu-invoicer -- --help -
Documentation: packages/quipu-invoicer/README.md
| Tool | Description |
|---|---|
| ecbx | Fetch and query exchange rates from the European Central Bank |
wise-exporter - Download bank statements from Wise with 2FA support
- Homepage: https://wise.com
- Usage:
nix run github:numtide/freelancer-toolbox#wise-exporter -- --help - Nix: nix/packages/wise-exporter.nix
- Documentation: packages/wise-exporter/README.md
paperless-cli - CLI for Paperless-ngx: manage documents, tags, mail accounts, and rules
- Homepage: https://docs.paperless-ngx.com
- Usage:
nix run github:numtide/freelancer-toolbox#paperless-cli -- --help - Nix: nix/packages/paperless-cli.nix
- Documentation: packages/paperless-cli/README.md
Add to your system configuration:
{
inputs = {
freelancer-toolbox.url = "github:numtide/freelancer-toolbox";
};
# In your system packages:
environment.systemPackages = with inputs.freelancer-toolbox.packages.${pkgs.stdenv.hostPlatform.system}; [
harvest-exporter
sevdesk-invoicer
wise-exporter
# ... other tools
];
}Note
This flake is built and tested against its pinned nixpkgs-unstable input.
If you set freelancer-toolbox.inputs.nixpkgs.follows = "nixpkgs", your
nixpkgs must also track nixpkgs-unstable and be reasonably current.
Run a specific tool directly without installing:
nix run github:numtide/freelancer-toolbox#harvest-exporter -- --help
nix run github:numtide/freelancer-toolbox#sevdesk-invoicer -- --help
nix run github:numtide/freelancer-toolbox#wise-exporter -- --help
# etc.Copy the environment template and fill in your API tokens:
cp .envrc.local-template .envrc.local
# Edit .envrc.local with your API tokens| Variable | Description |
|---|---|
HARVEST_ACCOUNT_ID |
Harvest account ID |
HARVEST_BEARER_TOKEN |
API token from Harvest Developers |
SEVDESK_API_TOKEN |
SevDesk API token |
WISE_API_TOKEN |
Wise API token |
WISE_PRIVATE_KEY |
RSA private key for Wise 2FA (see wise-exporter docs) |
WISE_PROFILE |
Wise business profile ID |
PAPERLESS_URL |
Paperless-ngx instance URL |
PAPERLESS_TOKEN |
Paperless API token |
QUIPU_APP_ID |
Quipu OAuth application ID |
QUIPU_APP_SECRET |
Quipu OAuth application secret |
KIMAI_API_URL |
Kimai instance API URL |
KIMAI_API_KEY |
Kimai API key |
Run any workspace tool directly from source:
uv sync # materialise .venv (one-time)
uv run harvest-exporter --help # or any other console scriptnix develop drops you into a shell with uv and the project formatters available. For a hermetic build of a specific tool:
nix run .#harvest-exporterThe workspace also contains sevdesk-api,
a library member (no CLI) used by the sevdesk tools.
# Format all code
nix fmt
# Run checks
nix flake checkThe commands below assume the tools are on your PATH — prefix with uv run
(see Development) or use nix run .#<package> if they are not.
Export your time tracking data and generate an invoice:
# From Harvest
harvest-exporter --format json > harvest.json
sevdesk-invoicer --customer "CUSTOMER_ID" harvest.json
# From Kimai
kimai-exporter --client "Acme Corp" > kimai.json
sevdesk-invoicer --customer "CUSTOMER_ID" kimai.jsonSee docs/workflows/monthly-invoicing.md for the complete guide including currency conversion and multi-user scenarios.
Export the annual CSV from numtide.harvestapp.com/reports?kind=year, then:
working-days-calculator annual-report.csv
# Working days: 220 from 2024-01-02 00:00:00 to 2024-12-31 00:00:00- Getting Started — set yourself up as a contractor (tax registration, insurance, banking)
- Monthly Invoicing — export time tracking data and generate invoices
- Country Guides — country-specific guidance for Germany, UK, Switzerland, and more
MIT