Command Line Tools

Documentation for the TagSpaces CLI (tscmd) for tagging, describing, indexing, generating thumbnails, and cleaning metadata — designed for automation and AI agentic workflows.

<TechArticleStructuredData />

Command Line Tools

tscmd is a command-line tool for managing files and folders used in TagSpaces Desktop and Web apps. It can add tags, set descriptions, generate search indexes, create thumbnails, and clean up orphaned metadata — all from the terminal.

<CenteredImage caption=“tscmd running in a terminal” src=“/media/core/tagspaces-command-line.avif” />

Because every command is non-interactive and produces structured output, tscmd integrates naturally into automation scripts, CI/CD pipelines, cron jobs, and AI agentic workflows where an LLM-based agent needs to organize, annotate, or prepare file collections programmatically.

The source code is available on GitHub.

Installation

npm install -g @tagspaces/shell

This makes the tscmd command available globally.

Commands Overview

All commands that take a directory argument accept multiple directories in a single invocation — for example tscmd indexer /path/a /path/b /path/c.

Tagging Files and Folders

Add one or more tags to files or folders:

tscmd tag /path/to/file.pdf -t invoice 2026 important

Tag multiple files at once:

tscmd tag /path/to/photo1.jpg /path/to/photo2.jpg -t vacation berlin

Options

The rename method embeds tags directly in the filename (e.g. report[invoice 2026].pdf). The sidecar method writes tags to a .ts/filename.json metadata file, leaving the original filename untouched. For folders, the sidecar method is always used regardless of the --method flag.

Tags are merged with any existing tags — duplicates are automatically avoided.

:::tip Use the sidecar method when filenames must remain stable, for example in version-controlled repositories or when other tools depend on exact filenames. :::

Setting Descriptions

Add a text description to a file or folder:

tscmd describe /path/to/file.pdf -d "Q1 financial report, reviewed by legal team"

Read the description from a file:

tscmd describe /path/to/photo.jpg -f /path/to/description.md

Read from stdin (useful for piping output from other tools):

echo "Generated summary" | tscmd describe /path/to/file.pdf -d -

Apply the same description to multiple entries:

tscmd describe /path/to/folder1 /path/to/folder2 -d "Archive - do not modify"

Options

Descriptions are stored in .ts/ sidecar files and are visible in the TagSpaces properties panel.

Search Index Generation

Create a search index for a folder and all its subfolders:

tscmd indexer /path/to/folder/

By default the index stores file and folder metadata only (tags, descriptions, sizes, timestamps). To also extract textual content from files for full-text search, add --fulltext:

tscmd indexer --fulltext /path/to/folder/

The extracted content covers plain text (.txt, .md, .marp), HTML (.htm, .html, .xhtml, .shtml, .mhtml), email (.eml), web shortcuts (.url, .website, .webloc, .desktop), tabular/contacts (.csv, .vcf), documents (.pdf, .docx, .odt), spreadsheets (.xlsx, .ods), presentations (.pptx, .odp), and ebooks (.epub).

Index multiple folders in one call:

tscmd indexer /path/to/folder1 /path/to/folder2

Options

Incremental indexing

Running tscmd indexer a second time on the same folder only re-processes files whose size or modification time changed, and prunes entries for files that were deleted. The command prints a summary line like:

  incremental: +3 ~1 -2 =1247

…meaning 3 files were added, 1 modified, 2 removed, and 1247 kept unchanged. Use --force to bypass the incremental path and rebuild everything.

After each run the CLI prints counts (files, folders, total size), full-text stats (files with text, token count) when --fulltext was used, and the elapsed time.

Output files

The index is split into two files inside .ts/:

Splitting the content keeps tsi.json small for fast loads, and lets the full-text file be streamed or partially re-read. Both files are used transparently by TagSpaces Desktop and Web.

Searching the Index

Query an existing index:

tscmd search /path/to/folder -q "quarterly report"

The search command reads .ts/tsi.json (and .ts/tsft.jsonl when the query contains free-text terms) and prints matching entries. It does not touch the filesystem beyond reading these index files, so it is fast and safe to run repeatedly.

Query syntax

The -q string mixes free-text terms with tag prefixes:

• Bare words — matched against filename, path, description, and extracted full-text
• +tag — entry must carry this tag (AND)
• -tag — entry must not carry this tag (NOT)
• |tag — entry carries at least one of these tags (OR)

Example combining all four:

tscmd search /documents -q "invoice +finance -draft |urgent"

Options

Narrow results to images tagged vacation but not private:

tscmd search /photos --type images -q "+vacation -private"

Strict substring search with no fuzzy matching:

tscmd search /notes -q "API key" -s strict

Thumbnail Generation

Recursively generate thumbnails for all supported files in a folder:

tscmd thumbgen /path/to/folder/

To include PDF thumbnail generation, add the -p flag:

tscmd thumbgen -p /path/to/folder/

Thumbnails are stored in the .ts/ subdirectory alongside the source files.

Cleaning Obsolete Metadata

Identify orphaned sidecar files and thumbnails that are no longer connected to existing files:

tscmd metacleaner /path/to/folder/

By default, this runs in analyze mode — it lists files that would be deleted without actually removing them. Review the output, then run with --analyze false to perform the actual cleanup:

tscmd metacleaner --analyze false /path/to/folder/

Options

Use in AI Agentic Workflows

The non-interactive, composable design of tscmd makes it well-suited for AI agent tool-use scenarios. An LLM agent with shell access can use these commands to organize and annotate files as part of a larger workflow.

Example: automated file organization

An AI agent processing a folder of downloaded documents could:

## Tag files based on content analysis
tscmd tag /downloads/report-q1.pdf -t finance quarterly 2026
tscmd tag /downloads/team-photo.jpg -t team event berlin

## Add AI-generated descriptions
echo "Quarterly financial report covering Q1 2026 revenue and expenses" \
  | tscmd describe /downloads/report-q1.pdf -d -

## Generate thumbnails and a full-text search index for the organized folder
tscmd thumbgen /downloads/
tscmd indexer --fulltext /downloads/

## Later, query the index
tscmd search /downloads/ -q "quarterly +finance"

Example: batch processing with pipes

Combine tscmd with standard Unix tools for batch operations:

## Tag all PDFs in a folder
find /documents -name "*.pdf" -exec tscmd tag {} -t document pdf \;

## Apply a description from a template file to multiple folders
for dir in /projects/*/; do
  tscmd describe "$dir" -f /templates/project-description.md
done

Why tscmd works well with AI agents

• Non-interactive — no prompts or confirmations (except metacleaner's analyze-first safety)
• Idempotent tagging — running the same tag command twice does not create duplicates
• Stdin support — agents can pipe generated text directly into tscmd describe
• Batch-friendly — multiple paths can be passed in a single command
• Structured metadata — all metadata is stored as JSON in .ts/ sidecar files, readable by both TagSpaces and other tools

Metadata Storage

All metadata generated by tscmd is stored in .ts/ subdirectories:

These files are automatically recognized by TagSpaces Desktop and Web applications.

Third Party Tools

Community tools compatible with TagSpaces metadata:

• TSS — a command-line tool to manage files with tags, with zsh completion support.