Text Analysis from the Command Line

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

02

Eight Analysis Commands plus a Repeatable Check Workflow

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|es
--format table|json|csv
--output <file>
--top <number>
--keep-stopwords
--stopwords <file>

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 the operation payload bounded by the selected --top value. Frequency, density, N-gram, Bag of Words, comparison, TF-IDF, and similarity payloads expose table-size or truncation metadata where rows can be cut. CSV uses explicit table labels when one operation returns several result sets.

07

Turn Existing Measurements into Repeatable CI Checks

textanalysis check composes exact phrase counts, word and repeated-phrase density, document length, and optional TF-IDF similarity to a local approved baseline. The command is diagnostic: it enforces thresholds your project chose and does not claim to score writing quality or guarantee rankings.

{
  "$schema": "https://textanalysis.tools/textanalysis-config.schema.json",
  "schemaVersion": 1,
  "requiredPhrases": ["text analysis"],
  "forbiddenPhrases": ["guaranteed ranking"],
  "minimumWords": 500,
  "maxTermDensity": 4,
  "maxPhraseDensity": 2,
  "maxSimilarity": 0.8,
  "baseline": "approved.md"
}

textanalysis check article.md
textanalysis check article.md --format json
textanalysis check article.md --format ci

The configuration must declare schemaVersion: 1. A failed rule exits with status 1; invalid configuration exits with status 2. Use the published JSON Schema for editor completion and validation. The repository's reusable GitHub Action runs the same npm package contract.

08

Import the Same Analysis Core from TypeScript

The npm package exposes a side-effect-free ESM entrypoint, so Node applications can analyze local text without launching a subprocess or sending it to the hosted API. Curated TypeScript declarations ship in the exact tarball.

import {
  analyzeBagOfWords,
  analyzeWordFrequency,
  calculateTextSimilarity,
  calculateTfIdfCorpus,
} from "textanalysis-tools";

const left = analyzeBagOfWords({text: "alpha beta alpha", language: "en"});
const right = analyzeBagOfWords({text: "alpha gamma", language: "en"});
const similarity = calculateTextSimilarity(left, right, "tfidf");

Stable exports cover word frequency, keyword density, N-grams, Bag of Words, Zipf diagnostics, TF-IDF, cosine similarity, token counting, and stop-word helpers.

09

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.

10

Expose the Eight Operations to AI Agents through MCP

The mcp command starts a local stdio server with eight read-only tools, validated input schemas, and structured results. Text arguments stay in the local process. Explicit public URL inputs are fetched and then analyzed locally.

npx --yes textanalysis-tools@0.2.0 mcp

Add the server to an MCP client that supports local stdio commands:

{
  "mcpServers": {
    "textanalysis": {
      "command": "npx",
      "args": ["--yes", "textanalysis-tools@0.2.0", "mcp"]
    }
  }
}

See the agent integration guide for the complete tool list, OpenAPI alternative, and data boundaries.

11

Choose CLI or MCP for Local Workflows and API for Applications

The CLI is suitable for files, shell pipelines, and scheduled jobs. MCP exposes the local engine directly to AI agents. The public API is suitable when an application or remote agent needs structured HTTP responses, OpenAPI discovery, and CORS.

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