dart-fss-cli 0.4.3 → 0.4.5

package/README.md

@@ -1,29 +1,26 @@
 # dart-fss-cli
 
+[![npm version](https://img.shields.io/npm/v/dart-fss-cli)](https://www.npmjs.com/package/dart-fss-cli)
+[![license](https://img.shields.io/npm/l/dart-fss-cli)](LICENSE)
+
 CLI for the Korea FSS [DART Open API](https://opendart.fss.or.kr) (Electronic Disclosure System).
 
-Access all DART API endpoints from the command line.
+Access all **83 DART API endpoints** from the command line. Designed for both humans and AI agents (Claude Code, etc.).
 
-**[한국어 가이드 (Korean Guide)](docs/ko.md)**
+**[Demo & Examples](DEMO.md)** | **[Agent Integration Guide](AGENTS.md)** | **[한국어 가이드](docs/ko.md)**
 
 ## Install
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/kiyeonjeon21/dart-fss-cli/main/install.sh | bash
+npx dart-fss-cli --help
 ```
 
-Or via npm:
+Runs instantly without installation. For global install:
 
 ```bash
 npm install -g dart-fss-cli
 ```
 
-Or run directly with npx:
-
-```bash
-npx dart-fss-cli --help
-```
-
 ## Setup
 
 Get an API key from [DART Open API](https://opendart.fss.or.kr).
@@ -35,49 +32,95 @@ export DART_API_KEY=your_api_key_here
 ## Usage
 
 ```bash
+# Look up a company (Korean name → corp_code)
+dart-fss lookup "삼성전자"
+
 # Company overview
 dart-fss disclosure company --corp "삼성전자" --pretty
 
-# Search disclosures
-dart-fss disclosure list --corp "카카오" --from 20240101 --to 20241231
+# Search filings
+dart-fss disclosure list --corp "카카오" --from 20250101 --to 20260101
 
-# Employee status
-dart-fss report employee --corp "삼성전자" --year 2024 --quarter annual
+# 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 "카카오" --year 2024 --quarter annual --pretty
+dart-fss financial single-account --corp "SK하이닉스" --year 2025 --quarter annual --pretty
 
-# Major holdings
-dart-fss equity major-stock --corp "삼성전자" --pretty
+# Major shareholding
+dart-fss equity major-stock --corp "네이버"
 
-# Look up corp_code by name
-dart-fss lookup "네이버"
-
-# List all endpoints
-dart-fss endpoints
-
-# Save output to file
+# 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` | Disclosures (search, company overview, documents) | 4 |
-| `report` | Periodic reports (employees, executives, dividends, etc.) | 28 |
-| `financial` | Financial data (statements, indices, XBRL) | 7 |
+| `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 event reports (capital changes, bonds, M&A, etc.) | 36 |
-| `securities` | Securities registration (equity, debt, mergers, etc.) | 6 |
+| `major` | Major events (capital changes, bonds, M&A, lawsuits) | 36 |
+| `securities` | Securities registration statements | 6 |
 
-## Global Options
+## Options
 
 | Option | Description |
 |--------|-------------|
-| `--api-key <key>` | DART API key (default: `DART_API_KEY` env) |
 | `--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:
+
+```bash
+# 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:
+
+```markdown
+## 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](AGENTS.md) and [DEMO.md](DEMO.md) for detailed examples.
 
 ## Programmatic Usage
 
@@ -85,7 +128,12 @@ dart-fss disclosure company --corp "삼성전자" --output result.json
 import { createDartProgram } from 'dart-fss-cli';
 
 const program = createDartProgram();
-await program.parseAsync(['node', 'dart-fss', 'disclosure', 'company', '--corp', '삼성전자', '--pretty']);
+await program.parseAsync([
+  'node', 'dart-fss',
+  'disclosure', 'company',
+  '--corp', '삼성전자',
+  '--pretty'
+]);
 ```
 
 ## License

package/dist/bin.js

@@ -2,7 +2,7 @@
 import {
   createDartProgram,
   formatErrorJson
-} from "./chunk-KPRBD4DH.js";
+} from "./chunk-JYPAIE4W.js";
 
 // src/bin.ts
 createDartProgram().parseAsync(process.argv).catch((err) => {

package/dist/{chunk-KPRBD4DH.js → chunk-JYPAIE4W.js}

@@ -1664,7 +1664,7 @@ function createDartProgram() {
   const program = new Command();
   program.name("dart-fss").description(
     'DART Open API CLI \u2014 access Korea Financial Supervisory Service (FSS) electronic disclosure system.\nProvides 83 API endpoints for company filings, financial statements, equity disclosures, and more.\nAuthentication: set DART_API_KEY env var or pass --api-key. Get a key at https://opendart.fss.or.kr\nCompanies are identified by 8-digit corp_code or company name. Use "dart-fss lookup <name>" to find corp_code.\nOutput is JSON by default (compact single-line). Use --pretty for formatted output.\nRate limit: approximately 20,000 requests per day per API key.'
-  ).version("0.4.3").option("--api-key <key>", "DART API key (default: DART_API_KEY env). Get one at https://opendart.fss.or.kr").option("--pretty", "Pretty-print JSON output (default: compact single-line JSON)").option("--output <file>", "Save result to file instead of stdout").option("--json <params>", "Pass raw API parameters as JSON string, bypassing flag parsing").option("--fields <f1,f2,...>", "Comma-separated field names to include in output (reduces response size for agents)").option("--dry-run", "Validate parameters and print the resolved API request without calling the API");
+  ).version("0.4.5").option("--api-key <key>", "DART API key (default: DART_API_KEY env). Get one at https://opendart.fss.or.kr").option("--pretty", "Pretty-print JSON output (default: compact single-line JSON)").option("--output <file>", "Save result to file instead of stdout").option("--json <params>", "Pass raw API parameters as JSON string, bypassing flag parsing").option("--fields <f1,f2,...>", "Comma-separated field names to include in output (reduces response size for agents)").option("--dry-run", "Validate parameters and print the resolved API request without calling the API");
   registerDisclosureCommands(program);
   registerPeriodicReportCommands(program);
   registerFinancialCommands(program);

package/dist/cli.js

@@ -1,6 +1,6 @@
 import {
   createDartProgram
-} from "./chunk-KPRBD4DH.js";
+} from "./chunk-JYPAIE4W.js";
 export {
   createDartProgram
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dart-fss-cli",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "DART (금융감독원 전자공시) Open API CLI",
   "type": "module",
   "bin": {