dart-fss-cli

CLI for the Korea FSS DART Open API (Electronic Disclosure System).

Access all 83 DART API endpoints from the command line. Designed for both humans and AI agents (Claude Code, etc.).

Demo & Examples | Agent Integration Guide | 한국어 가이드

Install

npx dart-fss-cli --help

Runs instantly without installation. For global install:

npm install -g dart-fss-cli

Setup

Get an API key from DART Open API.

export DART_API_KEY=your_api_key_here

Usage

# Look up a company (Korean name → corp_code)
dart-fss lookup "삼성전자"

# Company overview
dart-fss disclosure company --corp "삼성전자" --pretty

# Search filings
dart-fss disclosure list --corp "카카오" --from 20250101 --to 20260101

# Employee status (filtered fields)
dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual \
  --fields "sexdstn,fo_bbm,sm,avrg_cnwk_sdytrn"

# Financial statements
dart-fss financial single-account --corp "SK하이닉스" --year 2025 --quarter annual --pretty

# Major shareholding
dart-fss equity major-stock --corp "네이버"

# Save to file
dart-fss disclosure company --corp "삼성전자" --output result.json

Korean company names work directly. Companies registered with English names (NAVER, LG, etc.) can also be found using Korean input.

Command Groups

| Command | Description | APIs | |---------|-------------|------| | disclosure | Filings search, company overview, documents | 4 | | report | Periodic reports (employees, executives, dividends, audit) | 28 | | financial | Financial statements, indices, XBRL | 7 | | equity | Equity disclosure (major holdings, executive ownership) | 2 | | major | Major events (capital changes, bonds, M&A, lawsuits) | 36 | | securities | Securities registration statements | 6 |

Options

| Option | Description | |--------|-------------| | --pretty | Pretty-print JSON output | | --fields <f1,f2> | Filter response fields (saves context window for agents) | | --dry-run | Validate parameters without calling the API | | --output <file> | Save result to file | | --json <params> | Pass raw API parameters as JSON | | --api-key <key> | DART API key (default: DART_API_KEY env) |

Quarter Codes

| Value | Meaning | |-------|---------| | q1 | Q1 report | | half | Semi-annual | | q3 | Q3 report | | annual | Annual report |

Agent Integration

Built for AI agents to self-discover and call endpoints:

# Discover endpoints (auto-JSON when piped)
dart-fss endpoints --json-output

# Inspect parameter schema
dart-fss schema dividend

# Validate without API call
dart-fss report dividend --corp "삼성전자" --year 2025 --quarter annual --dry-run

# Structured JSON errors
# {"error":true,"code":"013","description":"No data found","message":"..."}

Add to your CLAUDE.md to use as a tool:

## Available Tools

dart-fss-cli is installed. Use it for Korean corporate disclosure data.

- `dart-fss endpoints --json-output` — list available APIs
- `dart-fss schema <endpoint>` — get parameter schema
- `dart-fss lookup <name>` — search company by name
- Always use `--fields` to limit response size
- Example: `dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual --fields "corp_name,sm"`

See AGENTS.md and DEMO.md for detailed examples.

Programmatic Usage

import { createDartProgram } from 'dart-fss-cli';

const program = createDartProgram();
await program.parseAsync([
  'node', 'dart-fss',
  'disclosure', 'company',
  '--corp', '삼성전자',
  '--pretty'
]);

License

MIT