dart-fss-cli 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +100 -47
  2. package/dist/bin.js +1 -1
  3. package/dist/{chunk-2OW5DY5B.js → chunk-537OSLFG.js} +1 -1
  4. package/dist/cli.js +1 -1
  5. package/package.json +3 -2
package/README.md CHANGED
@@ -1,91 +1,144 @@
1
1
  # dart-fss-cli
2
2
 
3
- CLI for the Korea FSS [DART Open API](https://opendart.fss.or.kr) (Electronic Disclosure System).
3
+ [![npm version](https://img.shields.io/npm/v/dart-fss-cli)](https://www.npmjs.com/package/dart-fss-cli)
4
+ [![license](https://img.shields.io/npm/l/dart-fss-cli)](LICENSE)
4
5
 
5
- Access all DART API endpoints from the command line.
6
+ 금융감독원 [DART Open API](https://opendart.fss.or.kr)의 **83개 전체 엔드포인트**를 커맨드라인에서 사용할 수 있는 CLI.
6
7
 
7
- **[한국어 가이드 (Korean Guide)](docs/ko.md)**
8
+ 사람이 직접 쓰기에도, AI 에이전트(Claude Code 등)에게 시키기에도 좋게 설계했습니다.
8
9
 
9
- ## Install
10
+ **[Demo & 사용 예시](DEMO.md)** | **[AI 에이전트 연동 가이드](AGENTS.md)** | **[한국어 가이드](docs/ko.md)**
10
11
 
11
- ```bash
12
- curl -fsSL https://raw.githubusercontent.com/kiyeonjeon21/dart-fss-cli/main/install.sh | bash
13
- ```
14
-
15
- Or via npm:
12
+ ## 설치
16
13
 
17
14
  ```bash
18
- npm install -g dart-fss-cli
15
+ npx dart-fss-cli --help
19
16
  ```
20
17
 
21
- Or run directly with npx:
18
+ 설치 없이 바로 실행됩니다. 글로벌 설치를 원하면:
22
19
 
23
20
  ```bash
24
- npx dart-fss-cli --help
21
+ npm install -g dart-fss-cli
25
22
  ```
26
23
 
27
- ## Setup
24
+ ## 사전 준비
28
25
 
29
- Get an API key from [DART Open API](https://opendart.fss.or.kr).
26
+ [DART Open API](https://opendart.fss.or.kr)에서 API 키를 발급받으세요.
30
27
 
31
28
  ```bash
32
29
  export DART_API_KEY=your_api_key_here
33
30
  ```
34
31
 
35
- ## Usage
32
+ ## 사용 예시
36
33
 
37
34
  ```bash
38
- # Company overview
39
- dart-fss disclosure company --corp "삼성전자" --pretty
35
+ # 회사 검색
36
+ dart-fss lookup "삼성전자"
40
37
 
41
- # Search disclosures
42
- dart-fss disclosure list --corp "카카오" --from 20240101 --to 20241231
38
+ # 기업 개황
39
+ dart-fss disclosure company --corp "삼성전자" --pretty
43
40
 
44
- # Employee status
45
- dart-fss report employee --corp "삼성전자" --year 2024 --quarter annual
41
+ # 공시 검색
42
+ dart-fss disclosure list --corp "카카오" --from 20250101 --to 20260101
46
43
 
47
- # Financial statements
48
- dart-fss financial single-account --corp "카카오" --year 2024 --quarter annual --pretty
44
+ # 직원 현황 (필요한 필드만)
45
+ dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual \
46
+ --fields "sexdstn,fo_bbm,sm,avrg_cnwk_sdytrn"
49
47
 
50
- # Major holdings
51
- dart-fss equity major-stock --corp "삼성전자" --pretty
48
+ # 재무제표
49
+ dart-fss financial single-account --corp "SK하이닉스" --year 2025 --quarter annual --pretty
52
50
 
53
- # Look up corp_code by name
54
- dart-fss lookup "네이버"
51
+ # 대량보유 상황
52
+ dart-fss equity major-stock --corp "네이버"
55
53
 
56
- # List all endpoints
57
- dart-fss endpoints
54
+ # 전환사채 발행 이력
55
+ dart-fss major convertible-bond --corp "카카오" --from 20230101 --to 20251231
58
56
 
59
- # Save output to file
57
+ # 결과를 파일로 저장
60
58
  dart-fss disclosure company --corp "삼성전자" --output result.json
61
59
  ```
62
60
 
63
- ## Command Groups
61
+ > 한글 회사명을 그대로 입력하면 됩니다. 영문 등록 회사(NAVER, LG 등)도 한글로 검색 가능합니다.
62
+
63
+ ## 커맨드 그룹
64
+
65
+ | 커맨드 | 설명 | API 수 |
66
+ |--------|------|--------|
67
+ | `disclosure` | 공시정보 (공시 검색, 기업 개황 등) | 4 |
68
+ | `report` | 정기보고서 (직원현황, 임원현황, 배당 등) | 28 |
69
+ | `financial` | 재무정보 (재무제표, 재무지표, XBRL) | 7 |
70
+ | `equity` | 지분공시 (대량보유, 임원 주요주주) | 2 |
71
+ | `major` | 주요사항보고서 (증자/감자, M&A 등) | 36 |
72
+ | `securities` | 증권신고서 (지분증권, 채무증권 등) | 6 |
73
+
74
+ ## 주요 옵션
75
+
76
+ | 옵션 | 설명 |
77
+ |------|------|
78
+ | `--pretty` | JSON 보기 좋게 출력 |
79
+ | `--fields <f1,f2>` | 응답 필드 필터링 (context window 절약) |
80
+ | `--dry-run` | API 호출 없이 파라미터 검증 |
81
+ | `--output <file>` | 결과를 파일로 저장 |
82
+ | `--json <params>` | raw API 파라미터를 JSON으로 직접 전달 |
83
+ | `--api-key <key>` | API 키 (기본: `DART_API_KEY` 환경변수) |
84
+
85
+ ## 분기 코드
64
86
 
65
- | Command | Description | APIs |
66
- |---------|-------------|------|
67
- | `disclosure` | Disclosures (search, company overview, documents) | 4 |
68
- | `report` | Periodic reports (employees, executives, dividends, etc.) | 28 |
69
- | `financial` | Financial data (statements, indices, XBRL) | 7 |
70
- | `equity` | Equity disclosure (major holdings, executive ownership) | 2 |
71
- | `major` | Major event reports (capital changes, bonds, M&A, etc.) | 36 |
72
- | `securities` | Securities registration (equity, debt, mergers, etc.) | 6 |
87
+ `--quarter` 옵션에 사용하는 값:
73
88
 
74
- ## Global Options
89
+ | 값 | 의미 |
90
+ |------|------|
91
+ | `q1` | 1분기 |
92
+ | `half` | 반기 |
93
+ | `q3` | 3분기 |
94
+ | `annual` | 사업보고서 |
95
+
96
+ ## AI 에이전트 연동
97
+
98
+ dart-fss-cli는 AI 에이전트가 스스로 API를 탐색하고 호출할 수 있도록 설계되었습니다.
99
+
100
+ ```bash
101
+ # 엔드포인트 탐색 (파이프 시 자동 JSON)
102
+ dart-fss endpoints --json-output
103
+
104
+ # 파라미터 스키마 조회
105
+ dart-fss schema dividend
106
+
107
+ # API 호출 없이 검증
108
+ dart-fss report dividend --corp "삼성전자" --year 2025 --quarter annual --dry-run
109
+
110
+ # 에러도 JSON
111
+ # {"error":true,"code":"013","description":"No data found","message":"..."}
112
+ ```
113
+
114
+ Claude Code의 `CLAUDE.md`에 추가하면 자연어로 DART 데이터를 조회할 수 있습니다:
115
+
116
+ ```markdown
117
+ ## Available Tools
118
+
119
+ dart-fss-cli가 설치되어 있습니다. 한국 기업의 공시 정보가 필요하면 사용하세요.
120
+
121
+ - `dart-fss endpoints --json-output` — 사용 가능한 API 목록
122
+ - `dart-fss schema <endpoint>` — API 파라미터 확인
123
+ - `dart-fss lookup <회사명>` — 회사 코드 검색
124
+ - 항상 `--fields`로 필요한 필드만 요청하세요
125
+ - 예시: `dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual --fields "corp_name,sm"`
126
+ ```
75
127
 
76
- | Option | Description |
77
- |--------|-------------|
78
- | `--api-key <key>` | DART API key (default: `DART_API_KEY` env) |
79
- | `--pretty` | Pretty-print JSON output |
80
- | `--output <file>` | Save result to file |
128
+ 자세한 내용은 [AGENTS.md](AGENTS.md)와 [DEMO.md](DEMO.md)를 참고하세요.
81
129
 
82
- ## Programmatic Usage
130
+ ## 프로그래밍 방식 사용
83
131
 
84
132
  ```typescript
85
133
  import { createDartProgram } from 'dart-fss-cli';
86
134
 
87
135
  const program = createDartProgram();
88
- await program.parseAsync(['node', 'dart-fss', 'disclosure', 'company', '--corp', '삼성전자', '--pretty']);
136
+ await program.parseAsync([
137
+ 'node', 'dart-fss',
138
+ 'disclosure', 'company',
139
+ '--corp', '삼성전자',
140
+ '--pretty'
141
+ ]);
89
142
  ```
90
143
 
91
144
  ## License
package/dist/bin.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  createDartProgram,
4
4
  formatErrorJson
5
- } from "./chunk-2OW5DY5B.js";
5
+ } from "./chunk-537OSLFG.js";
6
6
 
7
7
  // src/bin.ts
8
8
  createDartProgram().parseAsync(process.argv).catch((err) => {
package/dist/{chunk-2OW5DY5B.js → chunk-537OSLFG.js} RENAMED
@@ -1664,7 +1664,7 @@ function createDartProgram() {
1664
1664
  const program = new Command();
1665
1665
  program.name("dart-fss").description(
1666
1666
  '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.'
1667
- ).version("0.4.2").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");
1667
+ ).version("0.4.4").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");
1668
1668
  registerDisclosureCommands(program);
1669
1669
  registerPeriodicReportCommands(program);
1670
1670
  registerFinancialCommands(program);
package/dist/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  createDartProgram
3
- } from "./chunk-2OW5DY5B.js";
3
+ } from "./chunk-537OSLFG.js";
4
4
  export {
5
5
  createDartProgram
6
6
  };
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "dart-fss-cli",
3
- "version": "0.4.2",
3
+ "version": "0.4.4",
4
4
  "description": "DART (금융감독원 전자공시) Open API CLI",
5
5
  "type": "module",
6
6
  "bin": {
7
- "dart-fss": "dist/bin.js"
7
+ "dart-fss": "dist/bin.js",
8
+ "dart-fss-cli": "dist/bin.js"
8
9
  },
9
10
  "main": "./dist/cli.js",
10
11
  "types": "./dist/cli.d.ts",