npm package: @leppa/convert-to-wealthfolio
Description: Convert various CSV formats for import to Wealthfolio
Author: Oleksii Serdiuk
Latest version: 0.2.0

<!--
Copyright (c) 2026 Oleksii Serdiuk
SPDX-License-Identifier: BSD-3-Clause
-->

# Convert to Wealthfolio

[![Build Status Badge]][Build Status] [![CodeQL Analysis Badge]][CodeQL Analysis] [![SonarQube Quality Gate Badge]][SonarQube Quality Gate Status] [![Codecov Badge]][Codecov]

## About<!-- omit from toc -->

**Convert to Wealthfolio** is a command-line tool that converts various CSV formats into a format that can be imported into [Wealthfolio](#wealthfolio). The architecture uses a plugin-based system to support multiple input formats.

**Note**: This project targets Wealthfolio v3.x. CSVs generated by this tool may not be compatible with earlier versions.

## Table of Contents<!-- omit from toc -->

- [Features](#features)
- [What's New](#whats-new)
- [Supported Formats](#supported-formats)
- [Installing and Using the Converter](#installing-and-using-the-converter)
- [Building and Running From Source](#building-and-running-from-source)
- [Future Plans](#future-plans)
  - [What's Planned](#whats-planned)
  - [Adding CSV Formats](#adding-csv-formats)
  - [Adding Data Providers](#adding-data-providers)
  - [Adding Features and Improvements](#adding-features-and-improvements)
- [Getting Support](#getting-support)
  - [Reporting Issues](#reporting-issues)
  - [General Support](#general-support)
- [Technical Information](#technical-information)
- [Contributing Code and Documentation](#contributing-code-and-documentation)
- [Project Rationale](#project-rationale)
- [License](#license)
- [Attribution](#attribution)
  - [Wealthfolio](#wealthfolio)
  - [OSS Notices](#oss-notices)

## Features

- **TypeScript**: Full type safety and modern JavaScript features.
- **CLI Interface**: Command-line tool for easy conversion and automation.
- **Plugin Architecture**: Makes it easy to add new format converters by creating new plugins.
- **Format Detection**: Automatically detects input format.
- **Field Validation**: Validates all output records against activity type-specific field requirements.
- **Symbol Resolution**: Supports pluggable data providers for symbol, ISIN, CUSIP, and company name lookups.
- **Symbol Override and Mapping**: Allows overriding symbols and mapping them from ISINs, CUSIPs, and company names using an INI file.
- **Advanced Logging**: Colorized log output with configurable log verbosity levels.
- **Comprehensive Testing**: Full test coverage to ensure reliability.
- **Minimal Dependencies**: Only uses lean libraries as runtime dependencies with none or minimal transitive dependencies.

## What's New

See the [ChangeLog](./ChangeLog.md) for a detailed list of released and upcoming changes.

## Supported Formats

- **Generic**: Flexible CSV format with support for:
  - Standard transaction types (BUY, SELL, DEPOSIT, WITHDRAWAL, DIVIDENDS, etc.).
  - Optional instrument type, currency, fee, FX rate, and comment fields.
  - Supports symbol resolution via ISIN, CUSIP, or company name fields.
  - Respects the default currency option.
  - Comma-delimited format.
  - See the [Generic Format User Guide](./docs/generic-format-user-guide.md) for details.

- **Lime.co**: Transaction history CSV from the [**Lime Trading** brokerage](https://lime.co):
  - Supports forward and reverse splits by combining multiple records into one.
  - Extracts company names from the `Description` field and resolves symbols using data providers.
  - Ignores the `--default-currency` option since the brokerage only supports USD currency.
  - Semicolon-delimited format.
  - Has some quirks.
  - See the [Lime.co Format User Guide](./docs/limeco-format-user-guide.md) for details.

See the [Roadmap](./ROADMAP.md#format-plugins) for a list of formats that are planned to be added in the future.

## Installing and Using the Converter

Install the converter globally using `npm`:

```bash
npm install --global @leppa/convert-to-wealthfolio
```

This should make the `convert-to-wealthfolio` command available globally in your terminal.

Get help information about the CLI, its commands, and options:

```bash
convert-to-wealthfolio --help
```

Convert a CSV file:

```bash
convert-to-wealthfolio convert input.csv output.csv
```

See the [User Manual](./docs/user-manual.md#usage) for complete usage instructions, command examples, and available options.

## Building and Running From Source

Checkout the repository and install the dependencies:

```bash
git clone https://github.com/leppa/convert-to-wealthfolio.git
cd convert-to-wealthfolio
npm install
```

After this, the converter can be run using `npm start`:

```bash
npm start <command> -- [options]
```

See the [User Manual](./docs/user-manual.md#install-from-source) for complete instructions on building and running the converter from source.

## Future Plans

### What's Planned

See the [Roadmap](./ROADMAP.md) for a list of planned features and improvements.

### Adding CSV Formats

If your CSV format is not supported, you can create a new format plugin by extending the `BaseFormat` class. See the [Format Plugin Development Guide](./docs/format-plugin-development-guide.md) for instructions on how to create and integrate your own format into the converter.

If you don't know how to create a format plugin but want to see your format supported, you can open a new format request with a sample CSV file and the expected output. See [Requesting a New Format Plugin](./CONTRIBUTING.md#requesting-a-new-format-plugin) for guidelines on how to request a new format effectively.

### Adding Data Providers

If you want to add a new way of resolving symbols from ISINs, CUSIPs, or company names, you can create a new data provider by extending the `DataProvider` class. See the [Data Provider Development Guide](./docs/data-provider-development-guide.md) for instructions on how to create and integrate a new data provider into the converter.

Same as with format plugins, if you don't know how to create a data provider but want to see a new one supported, you can open a feature request with details about the data source. See [Requesting a New Feature](./CONTRIBUTING.md#requesting-a-new-feature) for guidelines on how to request new features effectively.

### Adding Features and Improvements

If you have an idea for a new feature or improvement, you can open a new feature request. See [Requesting a New Feature](./CONTRIBUTING.md#requesting-a-new-feature) for guidelines on how to request new features effectively.

## Getting Support

Only the latest release is officially supported and will receive bug fixes.

### Reporting Issues

For issues and bug reports, please open a new issue and use the appropriate template. See [Reporting Issues](./CONTRIBUTING.md#reporting-issues) for guidelines on how to report issues effectively.

### General Support

If you need support or have general questions, please open a new discussion on GitHub: <https://github.com/leppa/convert-to-wealthfolio/discussions>

## Technical Information

See the [Technical Information](./docs/technical-information.md) document for details about the architecture, design, and implementation of the project.

## Contributing Code and Documentation

If you want to contribute to the project, please refer to the [Contributing to Convert to Wealthfolio](./CONTRIBUTING.md) for guidelines on how to get involved.

## Project Rationale

I started this project mainly for myself to be able to import transaction history from my brokers into Wealthfolio. While Wealthfolio's import system is rather flexible, it still expects all transaction details to be in one row. However, some brokers export transactions in a way that splits details across multiple rows (e.g., one row for the main transaction and another for the associated fees). This made it difficult to import my data directly, so I decided to create a tool that could convert these formats into the one that Wealthfolio expects.

At some point during development I realized that Convert to Wealthfolio could be useful for other people as well, so I decided to open source it and make it extensible. I will most probably not implement any extra formats outside of the ones that I need myself, but I'm open to contributions from other people. Same goes for the feature requests - feel free to open a feature request, but I can't promise that I will implement it unless it's something that I need myself.

## License

Copyright © 2026 Oleksii Serdiuk  
All rights reserved.

This project is licensed under the **BSD 3-Clause License** - see [LICENSE](./LICENSE) for details.

## Attribution

### Wealthfolio

**Wealthfolio** is a trademark of Teymz Inc. This project is an independent tool and is not affiliated with or endorsed by Teymz Inc. in any way. See [wealthfolio.app](https://wealthfolio.app) for more information about **Wealthfolio**.

### OSS Notices

See the [NOTICE.md](./NOTICE.md) file for a list of license notices for third-party runtime dependencies used in this project.

<!-- References for badges -->

[Build Status]: https://github.com/leppa/convert-to-wealthfolio/actions/workflows/build-and-test.yml
[CodeQL Analysis]: https://github.com/leppa/convert-to-wealthfolio/actions/workflows/github-code-scanning/codeql
[SonarQube Quality Gate Status]: https://sonarcloud.io/summary/new_code?id=convert-to-wealthfolio
[Codecov]: https://codecov.io/github/leppa/convert-to-wealthfolio

<!-- Badge image URLs -->

[Build Status Badge]: https://github.com/leppa/convert-to-wealthfolio/actions/workflows/build-and-test.yml/badge.svg
[CodeQL Analysis Badge]: https://github.com/leppa/convert-to-wealthfolio/actions/workflows/github-code-scanning/codeql/badge.svg
[SonarQube Quality Gate Badge]: https://sonarcloud.io/api/project_badges/measure?project=convert-to-wealthfolio&metric=alert_status
[Codecov Badge]: https://codecov.io/github/leppa/convert-to-wealthfolio/graph/badge.svg?token=6UMNMGB3JP