Skype Archive CLI

Overview

Skype Archive CLI imports one uncompressed Skype export TAR into a local SQLite index, then provides fast local message, conversation, participant, and attachment browsing. The source archive is never modified and the application performs no network requests.

Privacy

All processing is local. The index and extracted-attachment cache under ~/.skype-archive-cli are unencrypted plaintext local data and can contain message text, names, identifiers, archive metadata, and attachment content. Protect them with the same care as the original export. The application uses private POSIX permissions where supported, but disk encryption and account security remain your responsibility. It performs no telemetry, update checks, or runtime network requests.

Prerequisites

• Node.js 24
• One uncompressed Skype export TAR
• A platform supported by better-sqlite3

Install

npm install -g skype-archive-cli --ignore-scripts=false

Quick Start

npm install -g skype-archive-cli --ignore-scripts=false
skype-archive import ~/Downloads/8_example_export.tar
skype-archive status
skype-archive messages "project update, deadline" --conv "=Synthetic Chat"
skype-archive convs Synthetic

CLI

Command reference

Command	Alias	Purpose	JSON result
import <export.tar>	-	Safely replace the active index from one uncompressed export TAR.	Object containing archivePath, exportDate, importedAt, conversations, participants, messages, mediaParts, attachmentReferences, structuralFingerprint, and peakHeapBytes.
status	-	Report index compatibility and source state.	Object containing indexed, compatible, and sourceState, plus paths, dates, schema version, and counts when a compatible index exists.
messages [query]	msg	Browse or search messages with filters and optional context.	`{ "messages": [...], "total": number, "conversationName": string
convs [query]	-	List conversations or select by ID, exact name, or partial text.	{ "conversations": [...] }
participants [query]	-	List participants or search IDs and display names.	{ "participants": [...] }
message <id>	-	Show one normalized message and its attachment metadata.	{ "message": {...} }
attachments <message-id>	-	List attachment parts referenced by a message.	{ "attachments": [...] }
attachment <id> [--output <path>]	-	Extract one attachment to managed cache or an explicit destination.	{ "attachment": { "path": string, "cached": boolean } }

Global options

Option	Meaning
--json	Write exactly one JSON document to stdout. Progress and diagnostics remain on stderr.
-n, --limit <number>	Set the maximum message, conversation, or participant results. Defaults to 20; accepts integers from 1 through 1,000.
-V, --version	Print the package version to stdout.
-h, --help	Print help to stdout.

messages options

Option	Meaning
--conv <selector>	Conversation ID, =exact display name, or literal partial ID/name.
--participant <selector>	Literal partial participant ID/display name.
--from <date>	Inclusive ISO date/timestamp or relative duration such as 3d.
--to <date>	Inclusive ISO date/timestamp or relative duration. A date-only value includes that UTC day.
--incoming	Return only incoming messages; conflicts with --outgoing.
--outgoing	Return only outgoing messages; conflicts with --incoming.
--type <type>	Match an exact Skype message type, for example RichText.
--has-attachment	Return only messages with indexed attachment references.
-A, --after <number>	Include 0 through 100 messages after each search match.
-B, --before <number>	Include 0 through 100 messages before each search match.
-C, --context <number>	Supply both context sides unless that side has an explicit -A or -B.

Context options require a non-empty search query.

attachment options

Option	Meaning
--output <path>	Write exclusively to a new file, or place the safe filename in an existing directory. Existing files and symlinks are not replaced or followed.

Human output is terminal-sanitized. Import progress and diagnostics use stderr. Interactive terminals receive one live progress line across scanning, message parsing, search indexing, finalization, and completion. Redirected stderr receives newline-delimited phase changes plus at most one ordinary update every five seconds. Progress contains only validated-offset archive percentage during scanning/message parsing and aggregate counts; --json stdout remains exactly one JSON document.

Message search treats spaces as OR and comma-separated groups as AND: hello world, deadline means (hello OR world) AND deadline. Filters include --conv, --participant, --from, --to, mutually exclusive --incoming/--outgoing, --type, and --has-attachment. -A, -B, and -C add 0 through 100 context messages around non-empty searches; -C supplies both sides unless -A or -B overrides that side.

Conversation selectors use an ID for an exact ID match, =Synthetic Chat for a case-insensitive exact display-name match, or plain Synthetic for a literal partial match. Exact names that identify multiple conversations report ambiguity instead of guessing.

Default attachment extraction uses the private managed cache and can reuse a validated cached file. --output accepts a new file path or an existing directory; destinations are created exclusively, so existing files and symlinks are never overwritten or followed.

JSON examples

With no active index, skype-archive status --json returns:

{"indexed":false,"compatible":false,"sourceState":"missing"}

A message search without context returns the exact top-level envelope below. Message objects contain the normalized list fields shown here:

{"messages":[{"rowId":42,"id":"synthetic-message-id","conversationId":"19:synthetic-thread","conversationName":"Synthetic Chat","senderId":"8:synthetic","senderName":"Synthetic User","timestamp":"2026-07-11T10:00:00.000Z","direction":"incoming","messageType":"Text","body":"Project update","attachmentCount":0,"isMatch":true}],"total":1,"conversationName":"Synthetic Chat"}

Context mode changes only the command envelope to grouped timelines:

{"groups":[{"conversationId":"19:synthetic-thread","messages":[{"rowId":42,"id":"synthetic-message-id","conversationId":"19:synthetic-thread","conversationName":"Synthetic Chat","senderId":"8:synthetic","senderName":"Synthetic User","timestamp":"2026-07-11T10:00:00.000Z","direction":"incoming","messageType":"Text","body":"Project update","attachmentCount":0,"isMatch":true}]}],"total":1,"conversationName":"Synthetic Chat"}

Inventory and extraction commands use command-specific envelopes. Each line below is a separate JSON document:

{"conversations":[]}
{"participants":[]}
{"attachments":[]}
{"attachment":{"path":"/tmp/synthetic-report.pdf","cached":false}}

Version 0.1 intentionally does not provide dedicated calls, unread state, or unanswered state. It supports one active archive only: there is no multi-archive merge or import through MCP.

See docs/MANUAL.md for the exact behavior and managed paths.

MCP

Import the export with the CLI before browsing it through MCP. The server still starts without an index so a client can list tools and call get_archive_status.

Run the published stdio executable without a global install:

npx -y --ignore-scripts=false -p skype-archive-cli skype-archive-mcp

Claude Desktop, Cursor, Codex, and other clients that accept stdio MCP JSON can use this configuration:

{
  "mcpServers": {
    "skype-archive": {
      "command": "npx",
      "args": ["-y", "--ignore-scripts=false", "-p", "skype-archive-cli", "skype-archive-mcp"]
    }
  }
}

The server registers exactly seven tools:

Tool	Purpose	Writes data
get_archive_status	Report index compatibility and source state.	No
get_messages	Browse or search messages with filters and context.	No
get_conversations	List/search conversations and filter their type.	No
get_participants	List/search participants.	No
get_message_by_id	Return one full, untruncated message.	No
get_attachments	List attachment metadata and availability.	No
extract_attachment	Copy one validated attachment into the managed private cache.	Cache only

The six query tools advertise read-only, non-destructive, idempotent, closed-world annotations. extract_attachment differs only by advertising readOnlyHint: false; it has no destination argument and can write only below ~/.skype-archive-cli/attachments.

MCP list limits default to 20 and accept 1 through 200. Context values accept 0 through 100. Bodies in get_messages results are limited to 8,000 Unicode code points and include bodyTruncated: true when shortened; use get_message_by_id for the full body and raw content. For example, an MCP client can call get_messages with invented arguments { "query": "synthetic deadline", "context": 2, "limit": 10 }, then call get_message_by_id with the returned invented ID.

MCP does not expose import, arbitrary extraction destinations, dedicated calls, unread state, or unanswered state.

If status reports indexed: true and compatible: false, the index schema does not match this release. Re-import the export with the CLI before browsing it; MCP never imports archives.

The TAR reader accepts conventional zero-block trailers and producer-compatible clean EOF exactly after a complete 512-byte-aligned entry. It still rejects partial headers, truncated entry data, invalid sizes and checksums, unsafe paths, links, and special entries.

Testing

npm install --ignore-scripts=false
npm test
npm run lint
npm run pack:check

Private-safe manual checks are documented in test/AI_MANUAL_TESTING.md.

Releases

Maintainers publish a stable GitHub Release whose tag exactly matches v<package version>. A token-free verification job repeats the Node 24 install, lint, test, and package checks; a separate minimal OIDC job then publishes a missing version to npm. Existing npm versions are skipped safely, and prereleases are never published to the stable npm channel.

License

AGPL-3.0-only. See LICENSE.