edgar-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Finlay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# edgar-cli
+
+Agent-friendly SEC EDGAR CLI for filings and company facts.
+
+## Features
+
+- `npx`-friendly Node/TypeScript package (no Python runtime needed)
+- JSON envelope output by default for stable automation
+- Strict SEC identity enforcement (`--user-agent` or `EDGAR_USER_AGENT`)
+- Core commands:
+  - `resolve`
+  - `filings list`
+  - `filings get`
+  - `facts get`
+
+## Install / Run
+
+```bash
+npx edgar-cli --help
+```
+
+Local development:
+
+```bash
+npm install
+npm run build
+node dist/cli.js --help
+```
+
+## SEC Identity Requirement
+
+SEC endpoints require declared automated access identity.
+
+Use either:
+
+```bash
+export EDGAR_USER_AGENT="Your Name your.email@example.com"
+```
+
+Or pass per command:
+
+```bash
+npx edgar-cli --user-agent "Your Name your.email@example.com" resolve AAPL
+```
+
+If identity is missing, commands fail with `IDENTITY_REQUIRED`.
+
+## Examples
+
+```bash
+# Resolve ticker -> canonical SEC identity mapping
+npx edgar-cli --user-agent "Your Name your.email@example.com" resolve AAPL
+
+# List recent 10-K filings
+npx edgar-cli --user-agent "Your Name your.email@example.com" filings list --id AAPL --form 10-K --query-limit 5
+
+# Get filing document URL by accession
+npx edgar-cli --user-agent "Your Name your.email@example.com" filings get --id AAPL --accession 0000320193-26-000006 --format url
+
+# Get concept data (latest per unit)
+npx edgar-cli --user-agent "Your Name your.email@example.com" facts get --id AAPL --taxonomy us-gaap --concept Revenues --latest
+```
+
+## Output Contract (default)
+
+All JSON-mode commands emit:
+
+```json
+{
+  "ok": true,
+  "command": "resolve",
+  "provider": "sec",
+  "data": {},
+  "error": null,
+  "meta": {
+    "timestamp": "2026-02-11T00:00:00Z",
+    "output_schema": "v1",
+    "view": "summary"
+  }
+}
+```
+
+## Compliance Notes
+
+- This CLI targets SEC-hosted endpoints only in V0.
+- Respect SEC fair-access guidance and use a valid identity in your user-agent.
+
+References:
+
+- [SEC Developer](https://www.sec.gov/developer)
+- [SEC Webmaster FAQ: code support](https://www.sec.gov/os/webmaster-faq#code-support)
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md) for vulnerability reporting guidance.
+
+## Development
+
+```bash
+npm run typecheck
+npm run test
+npm run build
+```

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+interface CliIo {
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+    env: NodeJS.ProcessEnv;
+}
+export declare function buildProgram(io: CliIo): Command;
+export declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from 'commander';
+import { pathToFileURL } from 'node:url';
+import { runFactsGet } from './commands/facts.js';
+import { runFilingsGet, runFilingsList } from './commands/filings.js';
+import { runResolve } from './commands/resolve.js';
+import { buildRuntimeOptions, parseDateString, parseNonNegativeInt, parsePositiveInt, requireUserAgent } from './core/config.js';
+import { failureEnvelope, successEnvelope } from './core/envelope.js';
+import { CLIError, ErrorCode, EXIT_CODE_MAP, isCLIError } from './core/errors.js';
+import { shapeData } from './core/output-shape.js';
+import { SecClient } from './sec/client.js';
+class CLIAbortError extends Error {
+    exitCode;
+    constructor(exitCode) {
+        super(`CLI exited with code ${exitCode}`);
+        this.exitCode = exitCode;
+        this.name = 'CLIAbortError';
+    }
+}
+function defaultIo() {
+    return {
+        stdout: (message) => process.stdout.write(message),
+        stderr: (message) => process.stderr.write(message),
+        env: process.env
+    };
+}
+function humanPrint(io, data) {
+    io.stdout(`${JSON.stringify(data, null, 2)}\n`);
+}
+function emitSuccess(params) {
+    const { context, io, command, result } = params;
+    if (context.runtime.humanMode) {
+        humanPrint(io, result.data);
+        return;
+    }
+    const shaped = shapeData({
+        data: result.data,
+        fields: context.runtime.fields,
+        limit: context.runtime.limit
+    });
+    const metaUpdates = {
+        ...(result.metaUpdates ?? {}),
+        ...shaped.metaUpdates
+    };
+    const envelope = successEnvelope({
+        command,
+        data: shaped.data,
+        view: context.runtime.view,
+        metaUpdates
+    });
+    io.stdout(`${JSON.stringify(envelope)}\n`);
+}
+function emitError(params) {
+    const { command, err, runtimeView, humanMode, io } = params;
+    if (humanMode) {
+        io.stderr(`${err.code} ${err.message}\n`);
+        return err.exitCode;
+    }
+    const envelope = failureEnvelope({
+        command,
+        code: err.code,
+        message: err.message,
+        retriable: err.retriable,
+        view: runtimeView
+    });
+    io.stdout(`${JSON.stringify(envelope)}\n`);
+    return err.exitCode;
+}
+function toCliError(err) {
+    if (isCLIError(err)) {
+        return err;
+    }
+    return new CLIError(ErrorCode.INTERNAL_ERROR, err.message || 'Unexpected error');
+}
+async function executeCommand(command, commandObj, io, handler) {
+    const globalOptions = commandObj.optsWithGlobals();
+    const runtime = buildRuntimeOptions({
+        json: globalOptions.json,
+        human: globalOptions.human,
+        view: globalOptions.view,
+        fields: globalOptions.fields,
+        limit: globalOptions.limit,
+        verbose: globalOptions.verbose,
+        userAgent: globalOptions.userAgent
+    }, io.env);
+    try {
+        const userAgent = requireUserAgent(runtime.userAgent);
+        const secClient = new SecClient({
+            userAgent,
+            verbose: runtime.verbose,
+            logger: (message) => io.stderr(`[debug] ${message}\n`)
+        });
+        const context = {
+            runtime,
+            secClient
+        };
+        const result = await handler(context);
+        emitSuccess({ command, result, context, io });
+    }
+    catch (error) {
+        const cliError = toCliError(error);
+        const exitCode = emitError({
+            command,
+            err: cliError,
+            runtimeView: runtime.view,
+            humanMode: runtime.humanMode,
+            io
+        });
+        throw new CLIAbortError(exitCode);
+    }
+}
+export function buildProgram(io) {
+    const program = new Command();
+    program
+        .name('edgar')
+        .description('Agent-friendly SEC EDGAR CLI')
+        .option('--json', 'Emit JSON envelope output (default)')
+        .option('--human', 'Emit human-readable output')
+        .option('--view <view>', 'Output view mode (summary|full)', 'summary')
+        .option('--fields <fields>', 'Select specific response fields in JSON mode')
+        .option('--limit <n>', 'Limit output rows in JSON mode')
+        .option('--verbose', 'Enable verbose debug logs')
+        .option('--user-agent <value>', 'SEC identity (required for network commands), e.g. "Name email@domain.com"')
+        .showHelpAfterError(true)
+        .exitOverride()
+        .addHelpText('after', '\nSEC identity is required for network commands.\nSet --user-agent or EDGAR_USER_AGENT.')
+        .configureOutput({
+        writeOut: (message) => io.stdout(message),
+        writeErr: (message) => io.stderr(message)
+    });
+    program
+        .command('resolve')
+        .description('Resolve ticker/CIK to canonical SEC identity fields')
+        .argument('<id>', 'Ticker (AAPL) or CIK (320193 / 0000320193)')
+        .action(async function actionResolve(id) {
+        await executeCommand('resolve', this, io, async (context) => runResolve(id, context));
+    });
+    const filings = program.command('filings').description('Query filing metadata and filing documents');
+    filings
+        .command('list')
+        .requiredOption('--id <id>', 'Ticker or CIK')
+        .option('--form <form>', 'SEC form type, e.g. 10-K')
+        .option('--from <yyyy-mm-dd>', 'Lower filing-date bound')
+        .option('--to <yyyy-mm-dd>', 'Upper filing-date bound')
+        .option('--query-limit <n>', 'Limit rows before envelope shaping')
+        .option('--offset <n>', 'Offset rows before query-limit slicing', '0')
+        .action(async function actionFilingsList(options) {
+        const from = options.from ? parseDateString(options.from, '--from') : undefined;
+        const to = options.to ? parseDateString(options.to, '--to') : undefined;
+        const queryLimit = options.queryLimit === undefined
+            ? undefined
+            : parsePositiveInt(options.queryLimit, '--query-limit');
+        const offset = parseNonNegativeInt(options.offset, '--offset');
+        await executeCommand('filings list', this, io, async (context) => runFilingsList({
+            id: options.id,
+            form: options.form,
+            from,
+            to,
+            queryLimit,
+            offset
+        }, context));
+    });
+    filings
+        .command('get')
+        .requiredOption('--id <id>', 'Ticker or CIK')
+        .requiredOption('--accession <accession>', 'Accession number: XXXXXXXXXX-XX-XXXXXX')
+        .option('--format <format>', 'url|html|text', 'url')
+        .action(async function actionFilingsGet(options) {
+        const format = options.format;
+        if (!['url', 'html', 'text'].includes(format)) {
+            throw new CLIAbortError(emitError({
+                command: 'filings get',
+                err: new CLIError(ErrorCode.VALIDATION_ERROR, '--format must be one of url|html|text'),
+                runtimeView: 'summary',
+                humanMode: false,
+                io
+            }));
+        }
+        await executeCommand('filings get', this, io, async (context) => runFilingsGet({
+            id: options.id,
+            accession: options.accession,
+            format: format
+        }, context));
+    });
+    const facts = program.command('facts').description('Query SEC company facts (XBRL)');
+    facts
+        .command('get')
+        .requiredOption('--id <id>', 'Ticker or CIK')
+        .option('--taxonomy <taxonomy>', 'us-gaap|dei')
+        .option('--concept <concept>', 'Concept name, e.g. Revenues')
+        .option('--unit <unit>', 'Unit key, e.g. USD')
+        .option('--latest', 'Return only latest point per unit')
+        .action(async function actionFactsGet(options) {
+        const taxonomyValue = options.taxonomy;
+        if (taxonomyValue && !['us-gaap', 'dei'].includes(taxonomyValue)) {
+            throw new CLIAbortError(emitError({
+                command: 'facts get',
+                err: new CLIError(ErrorCode.VALIDATION_ERROR, '--taxonomy must be us-gaap or dei'),
+                runtimeView: 'summary',
+                humanMode: false,
+                io
+            }));
+        }
+        await executeCommand('facts get', this, io, async (context) => runFactsGet({
+            id: options.id,
+            taxonomy: taxonomyValue,
+            concept: options.concept,
+            unit: options.unit,
+            latest: Boolean(options.latest)
+        }, context));
+    });
+    return program;
+}
+export async function runCli(argv, io = defaultIo()) {
+    const program = buildProgram(io);
+    try {
+        await program.parseAsync(argv, { from: 'user' });
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CLIAbortError) {
+            return error.exitCode;
+        }
+        if (error instanceof CommanderError) {
+            return error.exitCode;
+        }
+        const cliError = toCliError(error);
+        io.stderr(`${cliError.code} ${cliError.message}\n`);
+        return EXIT_CODE_MAP[cliError.code] ?? 10;
+    }
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    runCli(process.argv.slice(2)).then((exitCode) => {
+        process.exit(exitCode);
+    });
+}

package/dist/commands/facts.d.ts

@@ -0,0 +1,8 @@
+import { CommandContext, CommandResult } from '../core/runtime.js';
+export declare function runFactsGet(params: {
+    id: string;
+    taxonomy?: 'us-gaap' | 'dei';
+    concept?: string;
+    unit?: string;
+    latest?: boolean;
+}, context: CommandContext): Promise<CommandResult>;

package/dist/commands/facts.js

@@ -0,0 +1,125 @@
+import { CLIError, ErrorCode } from '../core/errors.js';
+import { companyFactsUrl } from '../sec/endpoints.js';
+import { resolveEntity } from '../sec/ticker-map.js';
+function buildConceptSummary(taxonomyFacts) {
+    return Object.entries(taxonomyFacts)
+        .map(([concept, payload]) => {
+        const units = Object.keys(payload.units ?? {});
+        return {
+            concept,
+            label: payload.label ?? null,
+            unit_count: units.length,
+            units
+        };
+    })
+        .sort((a, b) => a.concept.localeCompare(b.concept));
+}
+function pickLatest(points) {
+    if (points.length === 0) {
+        return null;
+    }
+    const sorted = [...points].sort((a, b) => {
+        const aKey = a.filed ?? a.end ?? '';
+        const bKey = b.filed ?? b.end ?? '';
+        return bKey.localeCompare(aKey);
+    });
+    return sorted[0] ?? null;
+}
+function selectTaxonomy(allFacts, concept, taxonomy) {
+    if (taxonomy) {
+        if (!allFacts[taxonomy]) {
+            throw new CLIError(ErrorCode.NOT_FOUND, `Taxonomy ${taxonomy} not found`);
+        }
+        return taxonomy;
+    }
+    const preferred = ['us-gaap', 'dei'];
+    for (const tax of preferred) {
+        if (allFacts[tax]?.[concept]) {
+            return tax;
+        }
+    }
+    const anyTaxonomy = Object.keys(allFacts).find((tax) => Boolean(allFacts[tax]?.[concept]));
+    if (anyTaxonomy) {
+        return anyTaxonomy;
+    }
+    throw new CLIError(ErrorCode.NOT_FOUND, `Concept ${concept} not found in company facts`);
+}
+export async function runFactsGet(params, context) {
+    const entity = await resolveEntity(params.id, context.secClient, { strictMapMatch: false });
+    const payload = await context.secClient.fetchSecJson(companyFactsUrl(entity.cik));
+    const allFacts = payload.facts ?? {};
+    if (!params.concept) {
+        if (params.taxonomy) {
+            const taxonomyFacts = allFacts[params.taxonomy];
+            if (!taxonomyFacts) {
+                throw new CLIError(ErrorCode.NOT_FOUND, `Taxonomy ${params.taxonomy} not found`);
+            }
+            return {
+                data: {
+                    cik: entity.cik,
+                    entityName: payload.entityName,
+                    taxonomy: params.taxonomy,
+                    concept_count: Object.keys(taxonomyFacts).length,
+                    concepts: buildConceptSummary(taxonomyFacts)
+                }
+            };
+        }
+        const taxonomySummary = Object.fromEntries(Object.entries(allFacts).map(([taxonomy, taxonomyFacts]) => [
+            taxonomy,
+            {
+                concept_count: Object.keys(taxonomyFacts).length
+            }
+        ]));
+        return {
+            data: {
+                cik: entity.cik,
+                entityName: payload.entityName,
+                taxonomies: taxonomySummary
+            }
+        };
+    }
+    const concept = params.concept;
+    const taxonomy = selectTaxonomy(allFacts, concept, params.taxonomy);
+    const conceptData = allFacts[taxonomy]?.[concept];
+    if (!conceptData) {
+        throw new CLIError(ErrorCode.NOT_FOUND, `Concept ${concept} not found in taxonomy ${taxonomy}`);
+    }
+    const rawUnits = conceptData.units ?? {};
+    let selectedUnits;
+    if (params.unit) {
+        if (!rawUnits[params.unit]) {
+            throw new CLIError(ErrorCode.NOT_FOUND, `Unit ${params.unit} not found for ${taxonomy}:${concept}`);
+        }
+        selectedUnits = {
+            [params.unit]: rawUnits[params.unit]
+        };
+    }
+    else {
+        selectedUnits = rawUnits;
+    }
+    if (params.latest) {
+        const latestByUnit = Object.fromEntries(Object.entries(selectedUnits).map(([unitName, points]) => [unitName, pickLatest(points)]));
+        return {
+            data: {
+                cik: entity.cik,
+                entityName: payload.entityName,
+                taxonomy,
+                concept,
+                label: conceptData.label ?? null,
+                description: conceptData.description ?? null,
+                latest: latestByUnit
+            }
+        };
+    }
+    return {
+        data: {
+            cik: entity.cik,
+            entityName: payload.entityName,
+            taxonomy,
+            concept,
+            label: conceptData.label ?? null,
+            description: conceptData.description ?? null,
+            units: selectedUnits
+        }
+    };
+}

package/dist/commands/filings.d.ts

@@ -0,0 +1,14 @@
+import { CommandContext, CommandResult } from '../core/runtime.js';
+export declare function runFilingsList(params: {
+    id: string;
+    form?: string;
+    from?: string;
+    to?: string;
+    queryLimit?: number;
+    offset?: number;
+}, context: CommandContext): Promise<CommandResult>;
+export declare function runFilingsGet(params: {
+    id: string;
+    accession: string;
+    format: 'url' | 'html' | 'text';
+}, context: CommandContext): Promise<CommandResult>;

package/dist/commands/filings.js

@@ -0,0 +1,113 @@
+import * as cheerio from 'cheerio';
+import { CLIError, ErrorCode } from '../core/errors.js';
+import { filingDocumentUrl, submissionsUrl } from '../sec/endpoints.js';
+import { dateInRange, normalizeAccession } from '../sec/normalizers.js';
+import { resolveEntity } from '../sec/ticker-map.js';
+function zipRecentFilings(cik, recent) {
+    if (!recent) {
+        return [];
+    }
+    const accessionNumbers = recent.accessionNumber ?? [];
+    const forms = recent.form ?? [];
+    const filingDates = recent.filingDate ?? [];
+    const reportDates = recent.reportDate ?? [];
+    const primaryDocuments = recent.primaryDocument ?? [];
+    const rowCount = accessionNumbers.length;
+    const rows = [];
+    for (let idx = 0; idx < rowCount; idx += 1) {
+        const accession = accessionNumbers[idx];
+        if (!accession) {
+            continue;
+        }
+        const primaryDocument = primaryDocuments[idx] ?? null;
+        const filingUrl = primaryDocument && primaryDocument.length > 0
+            ? filingDocumentUrl({
+                cik,
+                accession,
+                primaryDocument
+            })
+            : null;
+        rows.push({
+            accession,
+            form: forms[idx] ?? null,
+            filingDate: filingDates[idx] ?? null,
+            reportDate: reportDates[idx] ?? null,
+            primaryDocument,
+            filingUrl
+        });
+    }
+    return rows;
+}
+function extractTextFromHtml(content) {
+    const $ = cheerio.load(content);
+    return $.text().replace(/\s+/g, ' ').trim();
+}
+export async function runFilingsList(params, context) {
+    const entity = await resolveEntity(params.id, context.secClient, { strictMapMatch: false });
+    const submissions = await context.secClient.fetchSecJson(submissionsUrl(entity.cik));
+    const rows = zipRecentFilings(entity.cik, submissions.filings?.recent);
+    const normalizedForm = params.form?.toUpperCase();
+    const filteredRows = rows.filter((row) => {
+        if (normalizedForm && (row.form ?? '').toUpperCase() !== normalizedForm) {
+            return false;
+        }
+        if (!row.filingDate) {
+            return !params.from && !params.to;
+        }
+        return dateInRange(row.filingDate, params.from, params.to);
+    });
+    const offset = params.offset ?? 0;
+    const queryLimit = params.queryLimit ?? filteredRows.length;
+    const pagedRows = filteredRows.slice(offset, offset + queryLimit);
+    return {
+        data: pagedRows,
+        metaUpdates: {
+            query_total_count: filteredRows.length,
+            query_returned_count: pagedRows.length,
+            query_truncated: offset + pagedRows.length < filteredRows.length,
+            query_offset: offset
+        }
+    };
+}
+export async function runFilingsGet(params, context) {
+    const accession = normalizeAccession(params.accession);
+    const entity = await resolveEntity(params.id, context.secClient, { strictMapMatch: false });
+    const submissions = await context.secClient.fetchSecJson(submissionsUrl(entity.cik));
+    const rows = zipRecentFilings(entity.cik, submissions.filings?.recent);
+    const match = rows.find((row) => row.accession === accession);
+    if (!match) {
+        throw new CLIError(ErrorCode.NOT_FOUND, `Accession ${accession} not found in recent submissions for ${params.id}`);
+    }
+    if (!match.primaryDocument || !match.filingUrl) {
+        throw new CLIError(ErrorCode.NOT_FOUND, `No primary document found for accession ${accession}`);
+    }
+    if (params.format === 'url') {
+        return {
+            data: {
+                accession: match.accession,
+                form: match.form,
+                filingDate: match.filingDate,
+                reportDate: match.reportDate,
+                primaryDocument: match.primaryDocument,
+                url: match.filingUrl
+            }
+        };
+    }
+    const content = await context.secClient.fetchSecText(match.filingUrl);
+    if (params.format === 'html') {
+        return {
+            data: {
+                accession: match.accession,
+                url: match.filingUrl,
+                content
+            }
+        };
+    }
+    return {
+        data: {
+            accession: match.accession,
+            url: match.filingUrl,
+            content: extractTextFromHtml(content)
+        }
+    };
+}

package/dist/commands/resolve.d.ts

@@ -0,0 +1,2 @@
+import { CommandContext, CommandResult } from '../core/runtime.js';
+export declare function runResolve(id: string, context: CommandContext): Promise<CommandResult>;

package/dist/commands/resolve.js

@@ -0,0 +1,7 @@
+import { resolveEntity } from '../sec/ticker-map.js';
+export async function runResolve(id, context) {
+    const entity = await resolveEntity(id, context.secClient, { strictMapMatch: true });
+    return {
+        data: entity
+    };
+}

package/dist/core/config.d.ts

@@ -0,0 +1,23 @@
+export interface RuntimeOptions {
+    jsonMode: boolean;
+    humanMode: boolean;
+    view: 'summary' | 'full';
+    fields?: string[];
+    limit?: number;
+    verbose: boolean;
+    userAgent?: string;
+}
+export interface RuntimeInput {
+    json?: boolean;
+    human?: boolean;
+    view?: string;
+    fields?: string;
+    limit?: string | number;
+    verbose?: boolean;
+    userAgent?: string;
+}
+export declare function buildRuntimeOptions(input: RuntimeInput, env: NodeJS.ProcessEnv): RuntimeOptions;
+export declare function requireUserAgent(userAgent: string | undefined): string;
+export declare function parsePositiveInt(value: string, argName: string): number;
+export declare function parseNonNegativeInt(value: string, argName: string): number;
+export declare function parseDateString(value: string, argName: string): string;

package/dist/core/config.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { CLIError, ErrorCode } from './errors.js';
+import { parseFields } from './output-shape.js';
+const positiveIntSchema = z.coerce.number().int().min(1);
+const nonNegativeIntSchema = z.coerce.number().int().min(0);
+const dateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+export function buildRuntimeOptions(input, env) {
+    const humanMode = Boolean(input.human);
+    const jsonMode = !humanMode;
+    const view = input.view === 'full' ? 'full' : 'summary';
+    const parsedFields = parseFields(input.fields);
+    const parsedLimit = input.limit === undefined || input.limit === null
+        ? undefined
+        : parsePositiveInt(String(input.limit), '--limit');
+    return {
+        jsonMode,
+        humanMode,
+        view,
+        fields: parsedFields,
+        limit: parsedLimit,
+        verbose: Boolean(input.verbose),
+        userAgent: input.userAgent?.trim() || env.EDGAR_USER_AGENT?.trim() || undefined
+    };
+}
+export function requireUserAgent(userAgent) {
+    if (userAgent && userAgent.trim().length > 0) {
+        return userAgent.trim();
+    }
+    throw new CLIError(ErrorCode.IDENTITY_REQUIRED, 'Missing SEC identity. Set --user-agent "Name email@domain.com" or EDGAR_USER_AGENT.');
+}
+export function parsePositiveInt(value, argName) {
+    const parsed = positiveIntSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, `${argName} must be a positive integer`);
+    }
+    return parsed.data;
+}
+export function parseNonNegativeInt(value, argName) {
+    const parsed = nonNegativeIntSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, `${argName} must be a non-negative integer`);
+    }
+    return parsed.data;
+}
+export function parseDateString(value, argName) {
+    const parsed = dateSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, `${argName} must use YYYY-MM-DD`);
+    }
+    return parsed.data;
+}

package/dist/core/envelope.d.ts

@@ -0,0 +1,28 @@
+import { ErrorCode } from './errors.js';
+export interface BrokerError {
+    code: ErrorCode;
+    message: string;
+    retriable: boolean;
+}
+export interface OutputEnvelope {
+    ok: boolean;
+    command: string;
+    provider: 'sec';
+    data: unknown;
+    error: BrokerError | null;
+    meta: Record<string, unknown>;
+}
+export declare function successEnvelope(params: {
+    command: string;
+    data: unknown;
+    view: string;
+    metaUpdates?: Record<string, unknown>;
+}): OutputEnvelope;
+export declare function failureEnvelope(params: {
+    command: string;
+    code: ErrorCode;
+    message: string;
+    retriable?: boolean;
+    view: string;
+    metaUpdates?: Record<string, unknown>;
+}): OutputEnvelope;

package/dist/core/envelope.js

@@ -0,0 +1,37 @@
+function nowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+export function successEnvelope(params) {
+    return {
+        ok: true,
+        command: params.command,
+        provider: 'sec',
+        data: params.data,
+        error: null,
+        meta: {
+            timestamp: nowIso(),
+            output_schema: 'v1',
+            view: params.view,
+            ...(params.metaUpdates ?? {})
+        }
+    };
+}
+export function failureEnvelope(params) {
+    return {
+        ok: false,
+        command: params.command,
+        provider: 'sec',
+        data: null,
+        error: {
+            code: params.code,
+            message: params.message,
+            retriable: params.retriable ?? false
+        },
+        meta: {
+            timestamp: nowIso(),
+            output_schema: 'v1',
+            view: params.view,
+            ...(params.metaUpdates ?? {})
+        }
+    };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,17 @@
+export declare enum ErrorCode {
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    IDENTITY_REQUIRED = "IDENTITY_REQUIRED",
+    RATE_LIMITED = "RATE_LIMITED",
+    NOT_FOUND = "NOT_FOUND",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    PARSE_ERROR = "PARSE_ERROR",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+export declare const EXIT_CODE_MAP: Record<ErrorCode, number>;
+export declare class CLIError extends Error {
+    readonly code: ErrorCode;
+    readonly retriable: boolean;
+    constructor(code: ErrorCode, message: string, retriable?: boolean);
+    get exitCode(): number;
+}
+export declare function isCLIError(err: unknown): err is CLIError;

package/dist/core/errors.js

@@ -0,0 +1,35 @@
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ErrorCode["IDENTITY_REQUIRED"] = "IDENTITY_REQUIRED";
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["PARSE_ERROR"] = "PARSE_ERROR";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+export const EXIT_CODE_MAP = {
+    [ErrorCode.VALIDATION_ERROR]: 2,
+    [ErrorCode.IDENTITY_REQUIRED]: 3,
+    [ErrorCode.RATE_LIMITED]: 4,
+    [ErrorCode.NOT_FOUND]: 5,
+    [ErrorCode.NETWORK_ERROR]: 6,
+    [ErrorCode.PARSE_ERROR]: 7,
+    [ErrorCode.INTERNAL_ERROR]: 10
+};
+export class CLIError extends Error {
+    code;
+    retriable;
+    constructor(code, message, retriable = false) {
+        super(message);
+        this.code = code;
+        this.retriable = retriable;
+        this.name = 'CLIError';
+    }
+    get exitCode() {
+        return EXIT_CODE_MAP[this.code] ?? 10;
+    }
+}
+export function isCLIError(err) {
+    return err instanceof CLIError;
+}

package/dist/core/output-shape.d.ts

@@ -0,0 +1,10 @@
+export interface ShapedData {
+    data: unknown;
+    metaUpdates: Record<string, unknown>;
+}
+export declare function parseFields(raw: string | undefined): string[] | undefined;
+export declare function shapeData(params: {
+    data: unknown;
+    fields?: string[];
+    limit?: number;
+}): ShapedData;

package/dist/core/output-shape.js

@@ -0,0 +1,61 @@
+import { CLIError, ErrorCode } from './errors.js';
+export function parseFields(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    const fields = raw
+        .split(',')
+        .map((field) => field.trim())
+        .filter((field) => field.length > 0);
+    if (fields.length === 0) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, '--fields requires at least one field');
+    }
+    return [...new Set(fields)];
+}
+function projectObject(source, fields) {
+    const projected = {};
+    for (const field of fields) {
+        projected[field] = source[field];
+    }
+    return projected;
+}
+function applyFields(data, fields) {
+    if (!fields) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        if (data.length === 0) {
+            return data;
+        }
+        if (!data.every((item) => item && typeof item === 'object' && !Array.isArray(item))) {
+            throw new CLIError(ErrorCode.VALIDATION_ERROR, '--fields can only be applied to object results or lists of objects');
+        }
+        return data.map((item) => projectObject(item, fields));
+    }
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return projectObject(data, fields);
+    }
+    throw new CLIError(ErrorCode.VALIDATION_ERROR, '--fields can only be applied to object results or lists of objects');
+}
+export function shapeData(params) {
+    const fieldShaped = applyFields(params.data, params.fields);
+    const metaUpdates = {};
+    if (Array.isArray(fieldShaped) && typeof params.limit === 'number') {
+        if (params.limit < 1) {
+            throw new CLIError(ErrorCode.VALIDATION_ERROR, '--limit must be at least 1');
+        }
+        const totalCount = fieldShaped.length;
+        const data = fieldShaped.slice(0, params.limit);
+        metaUpdates.total_count = totalCount;
+        metaUpdates.returned_count = data.length;
+        metaUpdates.truncated = data.length < totalCount;
+        return {
+            data,
+            metaUpdates
+        };
+    }
+    return {
+        data: fieldShaped,
+        metaUpdates
+    };
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,10 @@
+import { RuntimeOptions } from './config.js';
+import { SecClient } from '../sec/client.js';
+export interface CommandContext {
+    runtime: RuntimeOptions;
+    secClient: SecClient;
+}
+export interface CommandResult {
+    data: unknown;
+    metaUpdates?: Record<string, unknown>;
+}

package/dist/core/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/sec/client.d.ts

@@ -0,0 +1,17 @@
+export interface SecClientOptions {
+    userAgent: string;
+    verbose?: boolean;
+    fetchImpl?: typeof fetch;
+    logger?: (message: string) => void;
+}
+export declare class SecClient {
+    private readonly userAgent;
+    private readonly verbose;
+    private readonly fetchImpl;
+    private readonly logger;
+    constructor(options: SecClientOptions);
+    fetchSecJson<T>(url: string): Promise<T>;
+    fetchSecText(url: string): Promise<string>;
+    private log;
+    private request;
+}

package/dist/sec/client.js

@@ -0,0 +1,154 @@
+import pLimit from 'p-limit';
+import { CLIError, ErrorCode } from '../core/errors.js';
+const REQUEST_INTERVAL_MS = 125;
+const MAX_ATTEMPTS = 4;
+const paceGate = pLimit(1);
+let nextAllowedAt = 0;
+const sleep = async (ms) => {
+    if (ms <= 0) {
+        return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, ms));
+};
+const jitter = () => Math.floor(Math.random() * 120);
+function retryAfterMs(headerValue) {
+    if (!headerValue) {
+        return null;
+    }
+    const seconds = Number.parseInt(headerValue, 10);
+    if (!Number.isNaN(seconds)) {
+        return Math.max(0, seconds * 1000);
+    }
+    const retryAt = Date.parse(headerValue);
+    if (Number.isNaN(retryAt)) {
+        return null;
+    }
+    return Math.max(0, retryAt - Date.now());
+}
+async function paceRequests() {
+    await paceGate(async () => {
+        const now = Date.now();
+        const delay = Math.max(0, nextAllowedAt - now);
+        if (delay > 0) {
+            await sleep(delay);
+        }
+        nextAllowedAt = Math.max(nextAllowedAt, Date.now()) + REQUEST_INTERVAL_MS;
+    });
+}
+function isUndeclaredAutomationBody(value) {
+    const lowered = value.toLowerCase();
+    return (lowered.includes('undeclared automated tool') ||
+        lowered.includes('please declare your traffic') ||
+        lowered.includes('acceptable policy'));
+}
+function isRetriableNetworkError(err) {
+    return err instanceof TypeError;
+}
+function toNetworkError(url, message, retriable = false) {
+    return new CLIError(ErrorCode.NETWORK_ERROR, `SEC request failed for ${url}: ${message}`, retriable);
+}
+function toRateLimitedError(url) {
+    return new CLIError(ErrorCode.RATE_LIMITED, `SEC rate limit reached for ${url}`, true);
+}
+export class SecClient {
+    userAgent;
+    verbose;
+    fetchImpl;
+    logger;
+    constructor(options) {
+        this.userAgent = options.userAgent;
+        this.verbose = options.verbose ?? false;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.logger = options.logger ?? (() => undefined);
+    }
+    async fetchSecJson(url) {
+        const raw = await this.request(url, 'json');
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            throw new CLIError(ErrorCode.PARSE_ERROR, `Unable to parse SEC JSON response from ${url}: ${error.message}`);
+        }
+    }
+    async fetchSecText(url) {
+        return this.request(url, 'text');
+    }
+    log(message) {
+        if (!this.verbose) {
+            return;
+        }
+        this.logger(message);
+    }
+    async request(url, kind) {
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+            try {
+                await paceRequests();
+                this.log(`GET ${url} (attempt ${attempt}/${MAX_ATTEMPTS})`);
+                const response = await this.fetchImpl(url, {
+                    method: 'GET',
+                    headers: {
+                        'User-Agent': this.userAgent,
+                        'Accept-Encoding': 'identity'
+                    }
+                });
+                if (response.status === 403) {
+                    const body = await response.text();
+                    if (isUndeclaredAutomationBody(body)) {
+                        throw new CLIError(ErrorCode.IDENTITY_REQUIRED, 'SEC rejected request as undeclared automation. Use a valid --user-agent or EDGAR_USER_AGENT.');
+                    }
+                    throw toNetworkError(url, '403 Forbidden');
+                }
+                if (response.status === 404) {
+                    throw new CLIError(ErrorCode.NOT_FOUND, `SEC resource not found at ${url}`);
+                }
+                if (response.status === 429) {
+                    if (attempt < MAX_ATTEMPTS) {
+                        const headerDelay = retryAfterMs(response.headers.get('retry-after'));
+                        const delay = headerDelay ?? 250 * 2 ** (attempt - 1) + jitter();
+                        this.log(`429 received, waiting ${delay}ms before retry`);
+                        await sleep(delay);
+                        continue;
+                    }
+                    throw toRateLimitedError(url);
+                }
+                if (response.status === 503) {
+                    if (attempt < MAX_ATTEMPTS) {
+                        const headerDelay = retryAfterMs(response.headers.get('retry-after'));
+                        const delay = headerDelay ?? 250 * 2 ** (attempt - 1) + jitter();
+                        this.log(`503 received, waiting ${delay}ms before retry`);
+                        await sleep(delay);
+                        continue;
+                    }
+                    throw toNetworkError(url, '503 Service Unavailable', true);
+                }
+                if (!response.ok) {
+                    if (response.status >= 500 && attempt < MAX_ATTEMPTS) {
+                        const delay = 250 * 2 ** (attempt - 1) + jitter();
+                        this.log(`HTTP ${response.status}, waiting ${delay}ms before retry`);
+                        await sleep(delay);
+                        continue;
+                    }
+                    throw toNetworkError(url, `HTTP ${response.status}`);
+                }
+                const body = await response.text();
+                if (kind === 'json' && body.trim().length === 0) {
+                    throw new CLIError(ErrorCode.PARSE_ERROR, `SEC returned empty JSON response from ${url}`);
+                }
+                return body;
+            }
+            catch (error) {
+                if (error instanceof CLIError) {
+                    throw error;
+                }
+                if (attempt < MAX_ATTEMPTS && isRetriableNetworkError(error)) {
+                    const delay = 250 * 2 ** (attempt - 1) + jitter();
+                    this.log(`Transient network error, waiting ${delay}ms before retry`);
+                    await sleep(delay);
+                    continue;
+                }
+                throw toNetworkError(url, error.message, isRetriableNetworkError(error));
+            }
+        }
+        throw toNetworkError(url, 'Request failed after retries');
+    }
+}

package/dist/sec/endpoints.d.ts

@@ -0,0 +1,10 @@
+export declare const SEC_DATA_HOST = "https://data.sec.gov";
+export declare const SEC_WWW_HOST = "https://www.sec.gov";
+export declare function submissionsUrl(cik: string): string;
+export declare function companyFactsUrl(cik: string): string;
+export declare function tickerMapUrl(): string;
+export declare function filingDocumentUrl(params: {
+    cik: string;
+    accession: string;
+    primaryDocument: string;
+}): string;

package/dist/sec/endpoints.js

@@ -0,0 +1,19 @@
+import { normalizeAccession, normalizeCik } from './normalizers.js';
+export const SEC_DATA_HOST = 'https://data.sec.gov';
+export const SEC_WWW_HOST = 'https://www.sec.gov';
+export function submissionsUrl(cik) {
+    const cik10 = normalizeCik(cik);
+    return `${SEC_DATA_HOST}/submissions/CIK${cik10}.json`;
+}
+export function companyFactsUrl(cik) {
+    const cik10 = normalizeCik(cik);
+    return `${SEC_DATA_HOST}/api/xbrl/companyfacts/CIK${cik10}.json`;
+}
+export function tickerMapUrl() {
+    return `${SEC_WWW_HOST}/files/company_tickers.json`;
+}
+export function filingDocumentUrl(params) {
+    const cikNumeric = String(Number.parseInt(normalizeCik(params.cik), 10));
+    const accessionNoDash = normalizeAccession(params.accession).replace(/-/g, '');
+    return `${SEC_WWW_HOST}/Archives/edgar/data/${cikNumeric}/${accessionNoDash}/${params.primaryDocument}`;
+}

package/dist/sec/normalizers.d.ts

@@ -0,0 +1,5 @@
+export declare function isLikelyCik(value: string): boolean;
+export declare function normalizeCik(value: string): string;
+export declare function normalizeTicker(value: string): string;
+export declare function normalizeAccession(value: string): string;
+export declare function dateInRange(value: string, from?: string, to?: string): boolean;

package/dist/sec/normalizers.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { CLIError, ErrorCode } from '../core/errors.js';
+const cikSchema = z.string().regex(/^\d{1,10}$/);
+const tickerSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9.-]{0,14}$/);
+const accessionSchema = z.string().regex(/^\d{10}-\d{2}-\d{6}$/);
+export function isLikelyCik(value) {
+    return /^\d+$/.test(value.trim());
+}
+export function normalizeCik(value) {
+    const trimmed = value.trim();
+    const parsed = cikSchema.safeParse(trimmed);
+    if (!parsed.success) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, `Invalid CIK: ${value}`);
+    }
+    return parsed.data.padStart(10, '0');
+}
+export function normalizeTicker(value) {
+    const trimmed = value.trim();
+    const parsed = tickerSchema.safeParse(trimmed);
+    if (!parsed.success) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, `Invalid ticker: ${value}`);
+    }
+    return parsed.data.toUpperCase();
+}
+export function normalizeAccession(value) {
+    const trimmed = value.trim();
+    const parsed = accessionSchema.safeParse(trimmed);
+    if (!parsed.success) {
+        throw new CLIError(ErrorCode.VALIDATION_ERROR, '--accession must match XXXXXXXXXX-XX-XXXXXX');
+    }
+    return parsed.data;
+}
+export function dateInRange(value, from, to) {
+    if (!from && !to) {
+        return true;
+    }
+    if (from && value < from) {
+        return false;
+    }
+    if (to && value > to) {
+        return false;
+    }
+    return true;
+}

package/dist/sec/ticker-map.d.ts

@@ -0,0 +1,16 @@
+import { SecClient } from './client.js';
+export interface TickerRecord {
+    cik_str: number;
+    ticker: string;
+    title: string;
+}
+export interface ResolvedEntity {
+    input: string;
+    cik: string;
+    cik_numeric: number;
+    ticker: string | null;
+    title: string | null;
+}
+export declare function resolveEntity(id: string, client: SecClient, options?: {
+    strictMapMatch?: boolean;
+}): Promise<ResolvedEntity>;

package/dist/sec/ticker-map.js

@@ -0,0 +1,57 @@
+import { CLIError, ErrorCode } from '../core/errors.js';
+import { tickerMapUrl } from './endpoints.js';
+import { isLikelyCik, normalizeCik, normalizeTicker } from './normalizers.js';
+let cachedMap = null;
+let cachedAtMs = 0;
+const CACHE_TTL_MS = 15 * 60 * 1000;
+async function getTickerMap(client) {
+    const now = Date.now();
+    if (cachedMap && now - cachedAtMs < CACHE_TTL_MS) {
+        return cachedMap;
+    }
+    const payload = await client.fetchSecJson(tickerMapUrl());
+    const records = Object.values(payload)
+        .filter((record) => record && typeof record === 'object')
+        .filter((record) => typeof record.cik_str === 'number' && typeof record.ticker === 'string');
+    cachedMap = records;
+    cachedAtMs = now;
+    return records;
+}
+function findByTicker(records, ticker) {
+    return records.find((record) => record.ticker.toUpperCase() === ticker);
+}
+function findByCik(records, cik10) {
+    const cikNumeric = Number.parseInt(cik10, 10);
+    return records.find((record) => record.cik_str === cikNumeric);
+}
+export async function resolveEntity(id, client, options) {
+    const strictMapMatch = options?.strictMapMatch ?? false;
+    const records = await getTickerMap(client);
+    if (isLikelyCik(id)) {
+        const cik = normalizeCik(id);
+        const cikNumeric = Number.parseInt(cik, 10);
+        const match = findByCik(records, cik);
+        if (!match && strictMapMatch) {
+            throw new CLIError(ErrorCode.NOT_FOUND, `No SEC ticker-map record found for CIK ${cik}`);
+        }
+        return {
+            input: id,
+            cik,
+            cik_numeric: cikNumeric,
+            ticker: match?.ticker ?? null,
+            title: match?.title ?? null
+        };
+    }
+    const ticker = normalizeTicker(id);
+    const match = findByTicker(records, ticker);
+    if (!match) {
+        throw new CLIError(ErrorCode.NOT_FOUND, `No SEC ticker-map record found for ticker ${ticker}`);
+    }
+    return {
+        input: id,
+        cik: String(match.cik_str).padStart(10, '0'),
+        cik_numeric: match.cik_str,
+        ticker: match.ticker,
+        title: match.title
+    };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "edgar-cli",
+  "version": "0.1.1",
+  "description": "Agent-friendly SEC EDGAR CLI",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "edgar": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/finlayi/edgar-cli.git"
+  },
+  "homepage": "https://github.com/finlayi/edgar-cli#readme",
+  "bugs": {
+    "url": "https://github.com/finlayi/edgar-cli/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "edgar",
+    "sec",
+    "cli",
+    "npx",
+    "filings"
+  ],
+  "dependencies": {
+    "cheerio": "^1.1.2",
+    "commander": "^14.0.1",
+    "p-limit": "^7.1.1",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "@typescript-eslint/eslint-plugin": "^8.44.0",
+    "@typescript-eslint/parser": "^8.44.0",
+    "eslint": "^8.57.1",
+    "nock": "^14.0.10",
+    "prettier": "^3.6.2",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}