kardscm is a local collection and deck manager for
KARDS.
It syncs the official card catalog into a local SQLite database, lets you keep your owned card quantities up to date, saves decks from KARDS client TXT files, and exports collection or deck data to XLSX, CSV, or JSON.
The tool is local-first:
- no account
- no hosted service
- no PyPI package
- database stored as
collection.dbin the working directory
- Syncs the full KARDS card catalog, including reserved and spawnable cards.
- Preserves user-managed card quantities across syncs.
- Shows catalog changes before applying them: new cards, changed stats/text, reserve transitions, and removed cards.
- Exports the collection to XLSX, CSV, or JSON.
- Updates card quantities from an edited XLSX export.
- Imports, adds, replaces, deletes, and exports saved decks.
- Provides a local browser UI for browsing, filtering, and editing quantities.
- Provides an admin-only local mode for full card-field correction with an automatic database backup.
- Tracks API contract drift against a committed baseline.
- Adds manually curated extra-ability tags for game-client-only mechanics not exposed by the official GraphQL API.
- Python 3.12+
- uv
kardscm is distributed only from GitHub. It is not published to PyPI.
git clone git@github.com:AABur/kardscm.git
cd kardscm
make syncFor an isolated command install:
pipx install git+https://github.com/AABur/kardscm.gitIf you installed via pipx, run kardscm directly. If you cloned the
repo and ran make sync, prefix each command with uv run (or
activate .venv first) so the console script is found:
# 1. Sync the card catalog into collection.db.
uv run kardscm sync
# 2. Open the local browser UI and edit quantities.
uv run kardscm web
# 3. Export your collection.
uv run kardscm export -f xlsx -o cards.xlsx
# 4. Add a deck exported from the KARDS client.
uv run kardscm deck add my-deck.txt
# 5. Export a saved deck.
uv run kardscm deck export -f xlsx -o deck.xlsxUse the global --lang flag before the subcommand:
kardscm --lang ru sync
kardscm --lang de export -f xlsx -o cards.xlsx
kardscm --lang zh-Hant webSupported codes: en, ru, de, fr, it, es, pt, pl, ja, ko,
zh, zh-Hant.
English and Russian are maintained. Other locale files may be partial; missing translation keys fall back to English and are reported in the CLI or web UI.
kardscm sync
kardscm sync --diff-only
kardscm sync --yes
kardscm sync --diff-report ./sync-report.mdsync fetches the official catalog, compares it with the local database, and
shows a diff before writing changes. Any rejected prompt aborts the sync and
leaves the database unchanged. A Markdown report is written whenever there are
changes.
--diff-only writes the report without modifying the database. --yes
auto-approves every category for scripted runs.
Sync also checks the live GraphQL response shape against
kardscm/data/api_baseline.json. If the API shape changes, kardscm writes
sync-schema-diff-*.md and sync-schema-observed-*.json files in the current
directory. This does not block the sync.
kardscm export -f xlsx -o cards.xlsx
kardscm export -f csv -o cards.csv
kardscm export -f json -o cards.jsonTo update quantities from an edited spreadsheet:
kardscm update -i cards.xlsxOnly the quantity column is read. Cards are matched by faction and title in the active language. Whitespace differences such as NBSP and double spaces are normalized.
kardscm web
kardscm web --port 9000
kardscm web --no-browser
kardscm --lang ru webThe web UI runs locally at 127.0.0.1:8765 by default. It provides collection
browsing, sorting, filters, card details, and quantity editing.
Click Edit to enable quantity changes. Quantity writes are server-side validated by rarity caps:
- Standard: 4
- Limited: 3
- Special: 2
- Elite: 1
kardscm web --admin
kardscm --lang ru web --adminAdmin mode is for trusted local correction of catalog data. It exposes editable card stats, categories, ability flags, extra-ability flags, reserved state, and localized title/text for the active locale.
Admin mode:
- only starts on localhost
- creates a timestamped database backup before startup
- shows the backup path in a red banner
- does not register admin routes unless
--adminis passed
kardscm deck add deck.txt
kardscm deck add *.txt
kardscm deck add deck.txt -u
kardscm deck add deck.txt -r
kardscm deck delete
kardscm deck export -f xlsx -o deck.xlsx
kardscm deck export -f json -o deck.jsondeck add is the preferred import path. It looks up cards by faction, falls
back to exile links when needed, checks collection quantities, and can update
or replace existing data:
--update/-u: raise collection quantities to match the deck--replace/-r: overwrite an existing saved deck with the same name
deck import still exists as a simpler single-file import path, but day-to-day
use should prefer deck add.
KARDS client TXT decks look like this:
My Deck Name
Major power: soviet
Ally: germany
HQ: some_hq_name
soviet:
4x (1K) Card Name One
2x (3K) Card Name Two
germany:
3x (2K) Card Name Three
%%DECKCODE...
Rules:
- first non-empty line is the deck name
Major power:is requiredAlly:andHQ:are optional- nation sections use
nation:headers - card rows use
<qty>x (<cost>K) <name> - the
%%deck-code line is optional
Maintainers can refresh the committed API baseline (run from a clone;
pipx users can drop the uv run prefix):
uv run kardscm baseline init
uv run kardscm baseline acceptUse baseline init after intentional API changes or a fresh baseline rebuild.
Use baseline accept after reviewing the latest sync-schema-observed-*.json
file from a sync drift report.
collection.db: local SQLite databasecollection.db.bak*: local backupssync-diff-*.md: sync reportssync-schema-diff-*.md: API drift reportssync-schema-observed-*.json: observed API snapshots- export files: whatever path you pass with
-o
Generated local data is intentionally not part of the repository.
Developer setup, architecture, release process, and maintainer workflows are in
CONTRIBUTING.md.
MIT