@arach/linea (CLI)

Command-line companion for Linea — a calm reading workspace where text becomes audio and highlights become conversations.

Quick Start

Open Linea (or install it if missing):

npx @arach/linea

Open a specific paper or book in Linea:

npx @arach/linea paper.pdf

Installation Methods

1. Homebrew Cask (Recommended for macOS)

brew install --cask arach/linea/linea

# If Linea was previously installed directly, adopt it with:
brew install --cask --adopt arach/linea/linea

# To upgrade via brew:
brew upgrade --cask linea

2. Quick Terminal One-Liner

# Install or automagically upgrade:
curl -fsSL https://uselinea.com/install.sh | bash

# Force reinstall or check status:
curl -fsSL https://uselinea.com/install.sh | bash -s -- --force
curl -fsSL https://uselinea.com/install.sh | bash -s -- --check

3. npm / npx

# Run on demand:
npx @arach/linea [document.pdf]

# Automagically upgrade to the latest release:
npx @arach/linea upgrade

# Or install globally:
npm install -g @arach/linea

4. Direct 1-Click Download

Download the universal signed & notarized macOS disk image directly from: https://download.uselinea.com/mac/latest?direct=1

CLI Commands

| Command | Description | | :--- | :--- | | linea | Open Linea.app (checks for updates, prompts to install if missing) | | linea <document> | Open a PDF, EPUB, or document in Linea.app | | linea install [--force] | Download, verify SHA-256, and install Linea.app to /Applications | | linea upgrade | Automagically upgrade Linea.app to the latest public release | | linea web [doc] | Open Linea Web Reader in your default browser | | linea info | Show local installation, semantic version status, and latest release | | linea library --help · linea library <command> --help | Every library command with its arguments and an example | | linea library list\|search\|sections\|read\|annotations\|position | JSON reads against the running Mac library (search --document <id> stays inside one book; sections <id> lists its chapters) | | linea library save\|queue\|annotate\|open | JSON mutations routed through the running app (annotate --author <name> records who made the mark; annotations --author <name> lists only theirs, in reading order) | | linea library queue-list\|dequeue\|set-position | Read the queue, take a document off it, move the reading position (--section or --page) | | linea library delete-annotation <doc> <annotation> | Delete one annotation | | linea library delete-document <doc> --yes | Delete a document, its files and annotations | | linea import <url\|file> [--read-now\|--queue] [--title hint] | Import into the running app. URLs use the app's import method (dedupes, joins in-flight imports); files use the library importer (images are OCR'd). --check <url> reports whether it is already in the library | | linea notes export <id> [--format md\|json] [--out file] | Export a document's highlights and notes in reading order, one heading per section, as Markdown (or JSON). With --out, writes the file and prints a JSON receipt | | linea ask <id> "question" [--section id] [--quote text] [--author name] | Ask the configured model; the exchange lands in the document's Ask thread, and a quoted ask leaves a question mark made by --author | | linea prepare <id> [--wait] | Auto-Format a text document (job) | | linea narrate <id> [--section id] [--limit n] [--wait] [--out dir] | Narrate with your cloud voice into the reader's cache; --out copies the audio files | | linea readout list [id] · generate <id> [--kind conversation\|summary] [--question] [--audience] [--cast n] [--minutes n] [--render] [--wait] · export <episode> [--out file] [--script file.md] | Readouts. Voices are synthesized (and billed) only with --render | | linea align <id> [--wait] | Download a publisher recording and align it for read-along (job) | | linea jobs list \| status <id> \| wait <id> \| cancel <id> | Long work; wait prints progress lines on stderr and the finished job on stdout | | linea keys list \| set <provider> \| remove <provider> | Provider keys (openai, elevenlabs, xai, openrouter). set reads the key from stdin; replies show only a masked tail | | linea account | Account, sync and provider status (read-only) | | linea mcp | Stdio MCP server exposing the same library tools | | linea --help | Display help and options |

Commands that return data (library, import, ask, jobs and the rest) print one JSON object, errors included. --help on any command prints plain text and exits 0; notes export prints the Markdown itself unless --out is given.

Library and MCP commands talk to the running Linea Mac app over the existing same-user Unix socket. They do not edit library.json, prompt to install, or check for updates. If Linea is not running they fail with appNotRunning.

Reading with an agent

A tested session from import to annotation, with every flag, is at uselinea.com/docs/agents. Before an agent marks up a reader's book, give it the annotation skill that ships in this package at skills/linea-annotate/SKILL.md (also at uselinea.com/docs/skills/linea-annotate/SKILL.md): few marks, exact quotes, notes in a reader's voice, and only its own marks removed.

Linea Local MCP

linea mcp is a stdio MCP server that gives a local agent host grounded access to the running Linea Mac app's library over its existing same-user Unix socket. No login, OAuth, HTTP listener, daemon or hosted service is involved; managed/remote operation is unsupported and a remote chat connector cannot reach the local socket. The host supplies reasoning, summaries and recommendations; Linea supplies library access and persistence only.

Full setup, trust model, limits and workflow examples: docs/local-mcp.md.

Setup

The CLI is published on npm as @arach/linea. The library commands and MCP tools talk to Linea for Mac while it is running. When a command needs a newer app than the one installed, the CLI answers appOutdated: run linea upgrade and relaunch Linea. (library sections, document-scoped search, book-file links, mark authors and reading-order listings need Linea for Mac 0.7.0 or later; on 0.6.0, sections answers appOutdated, the CLI filters search --document itself, and --author is ignored.)

Requires Node.js >= 18 and a running Mac build with the library bridge. For a published CLI, install it at a stable executable path, then point your MCP host at that absolute path. Linea does not edit host configuration for you.

npm install -g @arach/linea
command -v linea      # use this path below

{
  "mcpServers": {
    "linea": {
      "command": "/opt/homebrew/bin/linea",
      "args": ["mcp"]
    }
  }
}

Development-checkout fallback: "command": "node", "args": ["/absolute/path/to/linea/apps/cli/bin/linea.mjs", "mcp"].

Before you connect

• Configuring the MCP grants this same-user process library reads and writes (save, queue, annotate, open). Rely on your host's tool-approval settings for actions; Linea adds no approval dialog or read-only mode in V1.
• Removing the configuration disconnects that host. Quitting the Mac app makes library operations unavailable. Neither revokes other processes running under the same macOS user.
• Local transport is not local inference: the host may send retrieved text to its model provider. No source documents, queries or results are logged by default; MCP stdout is JSON-RPC only, diagnostics go to stderr.
• Documents and annotations are untrusted data, never instructions to the agent.

Tools and limits

Twenty-four tools. Fifteen mirror linea library <action> 1:1: library_list, library_search, library_sections, library_read, library_annotations, library_position, library_save, library_queue, library_queue_list, library_dequeue, library_annotate, library_delete_annotation, library_set_position, library_delete_document, library_open. The CLI spells multi-word actions with dashes (linea library set-position). The two delete tools carry the MCP destructive hint, and delete-document on the CLI requires --yes. Only library_open activates the reader; read tools never prompt to install, check for updates, or bring the app forward. linea_import and linea_notes_export run the same code as their commands, and the generation tools (linea_ask, linea_prepare, linea_narrate, linea_readout, linea_align, linea_jobs, linea_account) mirror the commands above. Provider keys are CLI-only.

| Surface | Default | Max | | :--- | :--- | :--- | | library_list page (zero-argument list returns up to 25) | 25 | 25 | | library_read characters | 4,000 | 16,000 | | library_search hits (capped count is not a total) | 20 | 50 | | library_annotations entries (previews capped at 8,000 UTF-8 bytes) | 8 | 8 |

Read offsets are opaque Swift Character offsets: resume from the returned nextOffset, never compute one. A chunk is a partial read; say which sections or chunks were read. Missing or ambiguous annotation quotes fail and write nothing.

Errors are structured JSON (appNotRunning, appOutdated, invalidArgument, timeout, importFailed). A timeout on a save means uncertain completion: inspect the library (search/list) before retrying — local-file imports and annotations are not idempotent.

linea library list
linea library search "causal inference"
linea library sections DOCUMENT_UUID
linea library search "exact phrase" --document DOCUMENT_UUID
linea library read DOCUMENT_UUID --section SECTION_UUID --offset 0 --limit 4000
linea library annotations DOCUMENT_UUID --limit 8
linea library position DOCUMENT_UUID
linea library save /absolute/path/paper.pdf
linea library save https://example.com/article
linea library queue DOCUMENT_UUID
linea library annotate DOCUMENT_UUID --section SECTION_UUID --quote "Exact passage" --kind marginNote --note "My note"   # kinds: highlight (default), marginNote, question, summary
linea library open DOCUMENT_UUID --section SECTION_UUID

LINEA_BRIDGE_SOCKET overrides the socket path for isolated integration fixtures. Leave it unset for the normal Mac library.

Configuration

Install the current CLI package from the configuration toolkit, then use:

linea config export > profile.json
linea config validate profile.json
linea config apply profile.json
linea config apply profile.json --write

Config commands use Bun. Export/apply target the native Mac app, defaulting to com.uselinea.mac; pass --domain for another build. Apply previews changes unless --write is supplied. Quit Linea before writing. Run linea config --help for details. Node.js 18+ remains required for the CLI entry point.

For package maintainers, node prepare.mjs (also run by prepack) copies the canonical configuration implementation and schema into the package. Source checkout commands work without packaging.

License

MIT © Linea