Command-line interface for Kaiord workout file conversion
npm install @kaiord/cliCommand-line interface for Kaiord workout file conversion. Convert workout files between FIT, KRD, TCX, and ZWO formats with ease.
Install globally using npm or pnpm:
``bash`
npm install -g @kaiord/cli
or
`bash`
pnpm add -g @kaiord/cli
After installation, the kaiord command will be available globally.
Convert workout files between different formats.
#### Basic Usage
`bash`
kaiord convert --input workout.fit --output workout.krd
#### FIT to KRD
`bash`
kaiord convert --input workout.fit --output workout.krd
#### KRD to FIT
`bash`
kaiord convert --input workout.krd --output workout.fit
#### Batch Conversion
Convert multiple files using glob patterns:
`bash`
kaiord convert --input "workouts/*.fit" --output-dir converted/
#### Format Override
Override automatic format detection:
`bash`
kaiord convert --input data.bin --input-format fit --output workout.krd
Perform round-trip validation to verify data integrity.
#### Basic Validation
`bash`
kaiord validate --input workout.fit
#### Custom Tolerances
Use a custom tolerance configuration file:
`bash`
kaiord validate --input workout.fit --tolerance-config tolerance.json
Example tolerance.json:
`json`
{
"time": { "absolute": 1, "unit": "seconds" },
"power": { "absolute": 1, "percentage": 1, "unit": "watts" },
"heartRate": { "absolute": 1, "unit": "bpm" },
"cadence": { "absolute": 1, "unit": "rpm" }
}
You can create a .kaiordrc.json file to set default options. The CLI will search for this file in:
1. Current working directory
2. User home directory (~/.kaiordrc.json)
CLI options always take precedence over config file defaults.
Create .kaiordrc.json in your project or home directory:
`json`
{
"defaultInputFormat": "fit",
"defaultOutputFormat": "krd",
"defaultOutputDir": "./converted",
"defaultToleranceConfig": "./tolerance.json",
"verbose": false,
"quiet": false,
"json": false,
"logFormat": "pretty"
}
- defaultInputFormat: Default input format (fit, krd, tcx, zwo)fit
- defaultOutputFormat: Default output format (, krd, tcx, zwo)pretty
- defaultOutputDir: Default output directory for batch conversions
- defaultToleranceConfig: Path to default tolerance configuration file
- verbose: Enable verbose logging by default
- quiet: Enable quiet mode by default
- json: Enable JSON output by default
- logFormat: Default log format ( or structured)
With a config file, you can simplify your commands:
`bashWithout config file
kaiord convert --input workout.fit --output workout.krd --output-format krd
CLI options override config defaults:
`bash
Config has verbose: true, but --quiet overrides it
kaiord convert --input workout.fit --output workout.krd --quiet
`Global Options
$3
`bash
Verbose output (detailed logging)
kaiord convert --input workout.fit --output workout.krd --verboseQuiet mode (errors only)
kaiord convert --input workout.fit --output workout.krd --quiet
`$3
`bash
JSON output (machine-readable)
kaiord convert --input workout.fit --output workout.krd --jsonForce pretty terminal output
kaiord convert --input workout.fit --output workout.krd --log-format prettyForce structured JSON logs
kaiord convert --input workout.fit --output workout.krd --log-format json
`Supported Formats
- FIT (.fit) - Garmin's binary workout file format
- KRD (.krd) - Kaiord's canonical JSON format
- TCX (.tcx) - Training Center XML format
- ZWO (.zwo) - Zwift workout XML format
$3
The CLI is designed with a plugin architecture that will allow third-party developers to add support for custom workout file formats without modifying the core library. See Plugin Architecture Documentation for details on the design.
Planned Features:
- Dynamic plugin discovery and loading
- Type-safe plugin interface
- Automatic format detection for plugin formats
- Plugin configuration via
.kaiordrc.json
- Plugin management commands (kaiord plugins list, install, etc.)Example Plugin Usage (Future):
`bash
Install a plugin
npm install -g @kaiord/plugin-gpxUse plugin format
kaiord convert --input workout.gpx --output workout.krd
`See Example GPX Plugin for a complete plugin implementation example.
Exit Codes
- 0: Success
- 1: Error (invalid arguments, file not found, parsing error, validation error)
Documentation
$3
- Getting Started - Installation and basic usage
- KRD Format Specification - Complete format documentation
- Deployment Guide - CI/CD and npm publishing
$3
- npm Publish Verification - Publishing checklist and verification
Development
`bash
Install dependencies
pnpm installBuild the CLI
pnpm buildRun in development mode
pnpm dev -- convert --input workout.fit --output workout.krdLink for local testing
npm link
kaiord --version
npm unlink -g
`Testing
Run the test suites:
`bash
Run all tests
pnpm testRun unit tests only
pnpm test:unitRun integration tests
pnpm test:integrationRun smoke tests
pnpm test:smokeRun tests in watch mode
pnpm test:watch
``MIT - See LICENSE file for details.