01

Install the npm Package

Install globally when you want the textanalysis executable available in your shell:

npm install --global textanalysis-tools
textanalysis --help

To run one command without a global installation, use npx:

npx --yes textanalysis-tools frequency article.txt
Runtime requirement

The published package requires Node.js 22.13 or newer. Check your runtime with node --version.

02

Eight Focused Text Analysis Commands

analyze

Bag of Words, focus phrases, and Zipf distribution diagnostics.

Web tool →
frequency

Complete word-frequency table with counts and normalized rates.

Web tool →
density

Unigram, bigram, trigram, and exact tracked-phrase density.

Web tool →
compare

Normalized word, bigram, metric, and Zipf changes between A and B.

Web tool →
ngram

Phrase windows from one to ten tokens with count filtering.

Web tool →
bow

Complete Bag of Words vector for downstream processing.

Web tool →
tfidf

TF-IDF vectors and global IDF table across 2–10 documents.

Web tool →
similarity

BoW or TF-IDF cosine similarity with contribution terms.

Web tool →

03

Use Files, URLs, Inline Text, or stdin

A positional input can be a UTF-8 local file, a public HTTP(S) URL, or - for stdin. Single-input commands also accept --text and --url. Pair commands accept two positionals or the --text-a, --url-a, --text-b, and --url-b options.

textanalysis frequency --text "alpha beta alpha"
textanalysis bow --url https://example.com/article
textanalysis compare --text-a "old draft text" --text-b "new draft text"
textanalysis similarity --url-a https://example.com/a --url-b https://example.com/b --method bow

The tfidf command accepts 2–10 positional inputs. They can be files and public URLs in the same corpus. stdin can be consumed once per process.

04

Copy-and-Paste CLI Examples

textanalysis frequency article.txt
cat article.txt | textanalysis density --keywords "text analysis,SEO" --format json
textanalysis ngram https://example.com/article --size 3 --format csv
textanalysis compare original.txt revision.txt --format json
textanalysis tfidf draft.txt competitor.txt reference.txt --output tfidf.json --format json
textanalysis similarity draft.txt competitor.txt --method tfidf

Use shell quoting around inline text, focus phrases, and tracked keywords. A custom output file is written only after the operation completes successfully.

05

Common Options

--language auto|en|ru|uk
--format table|json|csv
--output <file>
--top <number>
--keep-stopwords
--stopwords <file>
--languageauto · en · ru · uk

Controls language detection and the default stop-word list.

--formattable · json · csv

Selects terminal-friendly output or a machine-readable serialization.

--topinteger

Limits result rows. Command-specific minimum and maximum values are validated.

--keep-stopwordsboolean flag

Includes the default function words in analysis.

--stopwordsUTF-8 file

Replaces the selected language list with a custom newline- or comma-separated list.

--outputfile path

Saves the selected format instead of writing the result to stdout.

Command-specific options include --focus, --tolerance, --keywords, --min-count, --size, and --method bow|tfidf. Run textanalysis --help for the complete contract.

06

Output Formats and Exit Codes

Table output is optimized for interactive terminal review. JSON includes the command, package version, generation time, input labels, local-storage declaration, settings, and complete operation payload. CSV uses explicit table labels when one operation returns several result sets.

Exit 0

The operation completed successfully, help/version was printed, or a downstream pipe closed normally.

Exit 2

The command, option, input count, or option value failed usage validation.

Exit 1

An operational error occurred while reading, fetching, analyzing, or writing data.

stderr

Error messages go to stderr, leaving stdout available for JSON, CSV, and shell pipelines.

07

Local-First Privacy and Public URL Inputs

Inline text, local files, and stdin are analyzed inside the CLI process and are not sent to textanalysis.tools. When a command receives a public URL, the CLI downloads that page directly, removes non-content markup, and analyzes the extracted text locally.

Only public HTTP and HTTPS URLs are accepted. Private and local-network destinations are rejected. Follow the source site's terms, access rules, and applicable data requirements when processing remote content.

08

Choose CLI for Local Workflows and API for Applications

The CLI is suitable for files, shell pipelines, scheduled local jobs, and analysis that should remain on one machine. The public API is suitable when a web application or agent needs structured HTTP responses, OpenAPI discovery, and CORS.

Same analysis primitives

The CLI and versioned API share the project's analysis implementation, but their transport, limits, and input handling are documented separately.

Read the API documentation or import the OpenAPI specification when HTTP integration is the better fit.

Package and source

VERSION 0.1.1 · EIGHT COMMANDS

Run one analysis without installing anything

Use npx with a local file, public URL, inline string, or piped text.

Open the npm package →