Ethical Literature Review CLI

A command-line tool for analyzing academic papers (PDF & DOCX) using the Ethical Literature Review API. Get citation annotations, methodology feedback, and quality suggestions — all from your terminal.

Quick Start

# Install globally
npm install -g @ethical/literature-review-cli

# Configure
cp .env.example .env
# Edit .env with your API URL and API key

# Analyze a paper
ethical analyze paper.pdf

# Interactive file picker
ethical analyze

Installation

npm install -g @ethical/literature-review-cli

Or use directly with npx:

npx @ethical/literature-review-cli analyze paper.pdf

Configuration

Create a .env file in your working directory:

# Required: Your Ethical API server URL
ETHICAL_API_URL=https://your-api-gateway-url.amazonaws.com/dev

# Authentication (provide one):
ETHICAL_API_KEY=elr_your_api_key_here
# OR
ETHICAL_SESSION_TOKEN=ses_your_session_token_here

You can get an API key from the Ethical web app under Settings → API Keys, or use ethical login to get a session token.

Commands

ethical analyze [file]

Analyze a PDF or DOCX paper for citation accuracy, methodology, clarity, and more.

# Analyze a specific file
ethical analyze paper.pdf

# Interactive file picker (scans current directory)
ethical analyze

# Output raw JSON
ethical analyze paper.pdf --json

# Save results to a file
ethical analyze paper.pdf --output results.json

# Also upload the paper to your account
ethical analyze paper.pdf --upload

Output includes:

• Annotations — specific issues found with quotes and comments, categorized as: citation, accuracy, clarity, methodology, missing-citation, strength
• Suggestions — general improvement recommendations
• Token usage — API tokens consumed

ethical review <topic>

Run an AI-powered literature review on any research topic.

ethical review "machine learning in healthcare diagnostics"
ethical review "quantum computing error correction" --json
ethical review "CRISPR gene therapy" --output review.json

ethical login

Authenticate and get a session token.

ethical login
ethical login --email [email protected] --password mypassword

ethical whoami

Check your current authentication status.

ethical whoami

ethical papers

List your uploaded papers.

ethical papers
ethical papers --json

ethical analyses

List your past paper analyses.

ethical analyses
ethical analyses --json

ethical usage

Show your API token usage statistics.

ethical usage
ethical usage --json

JSON Output

Use the --json flag on any command to get machine-readable output. Example analysis output:

{
  "annotations": [
    {
      "quote": "studies show that 90% of patients...",
      "comment": "This claim lacks a specific citation. Consider adding a reference.",
      "type": "missing-citation"
    },
    {
      "quote": "the methodology follows standard practice",
      "comment": "The methodology section is well-structured and clearly described.",
      "type": "strength"
    }
  ],
  "suggestions": [
    "Add a limitations section discussing potential biases in the dataset.",
    "Consider including more recent references from 2024-2025."
  ],
  "paperFilename": "paper.pdf",
  "tokenUsage": {
    "inputTokens": 12500,
    "outputTokens": 800,
    "totalTokens": 13300
  }
}

Programmatic Usage

The CLI can also be imported as a library:

import { EthicalApiClient, loadConfig, extractText } from "@ethical/literature-review-cli";

const config = loadConfig();
const client = new EthicalApiClient(config);

// Extract text from a local file
const { text } = await extractText("./paper.pdf");

// Analyze
const result = await client.analyzeCitations(text);
console.log(result.annotations);

Supported File Types

| Format | Extension | Notes | |--------|-----------|-------| | PDF | .pdf | Text-based PDFs. Scanned PDFs may have limited text extraction. | | DOCX | .docx | Microsoft Word (2007+) format. |

Requirements

• Node.js 18 or later
• An Ethical Literature Review API account and API key

License

MIT