diff --git a/README.md b/README.md index 580b54d..f07f102 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,71 @@ # edinet-cli -EDINET API v2 のコマンドラインクライアント。AI エージェントによる自律的な書類取得・分析に最適化されています。 +EDINET API v2 の Go 製 CLI ラッパー。AIエージェントによる自律的な日本企業の開示書類取得・財務分析に最適化。 [![CI](https://github.com/beatinaniwa/edinet-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/beatinaniwa/edinet-cli/actions/workflows/ci.yml) [![Go](https://img.shields.io/badge/Go-1.26-00ADD8.svg)](https://go.dev/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -## 概要 +## AIエージェント向けクイックリファレンス + +> **AI エージェントはまず `edinet-cli schema commands` を実行してください。** 全コマンドのフラグ・型・使用例が JSON で返ります。 + +### 出力規約 + +| ストリーム | 内容 | パース方法 | +|-----------|------|-----------| +| stdout | 構造化データ（JSON / table） | `json.Unmarshal` 等 | +| stderr | エラー（JSON）、進捗、デバッグ | 人間向け、パース不要 | + +### 終了コード + +| コード | 意味 | 対処 | +|--------|------|------| +| 0 | 成功（部分成功を含む） | 結果をそのまま利用 | +| 1 | 一般エラー | stderr を確認 | +| 2 | バリデーションエラー（引数不正） | コマンドの使い方を修正 | +| 3 | 認証エラー | `EDINET_API_KEY` を確認 | +| 4 | APIエラー（400/404/500） | リクエスト内容を見直し | + +### スキーマ自己記述（`schema` コマンド群） + +AIエージェントが CLI の能力を事前に把握するための機械可読メタデータ: + +```bash +edinet-cli schema commands # 全コマンド・フラグ・型・使用例（JSON） +edinet-cli schema doc-types # 書類種別コード一覧（42種、例: 120=有価証券報告書） +edinet-cli schema sections # テキスト抽出可能なセクション一覧 +edinet-cli schema financial-elements # 財務XBRL要素マッピング一覧 +edinet-cli schema derived-metrics # 派生財務指標（ROE, ROA等）の計算式一覧 +``` + +### 典型的なワークフロー例 + +```bash +# 1. 企業を特定 +edinet-cli company search トヨタ + +# 2. 直近の有価証券報告書を探す +edinet-cli company filings 7203 --doc-type 120 --limit 3 -[EDINET](https://disclosure.edinet-fsa.go.jp/)（Electronic Disclosure for Investors' NETwork）は、金融庁が運営する有価証券報告書等の開示書類の電子開示システムです。 +# 3. 財務データを構造化抽出（複数期間） +edinet-cli company financials 7203 --periods 5 --summary-only + +# 4. 特定書類のリスク情報をテキスト抽出 +edinet-cli doc text S100XXXX --section risk +``` -`edinet-cli` は EDINET API v2 を Go で薄くラップした CLI ツールで、以下の特徴を持ちます： +--- -- **構造化出力**: stdout にはすべて JSON（または `--format table` でテーブル形式）を出力 -- **決定論的な終了コード**: 自動化やエラーハンドリングが容易 -- **スキーマ自己記述**: `schema` コマンドで CLI の全機能を機械可読な形式で取得可能 -- **ローカルキャッシュ**: API レスポンスをキャッシュし、不要なリクエストを削減 +## 概要 -## 特徴 +[EDINET](https://disclosure.edinet-fsa.go.jp/) は金融庁が運営する有価証券報告書等の電子開示システムです。`edinet-cli` はその API v2 を薄くラップし、以下を提供します: -- 日付・期間指定による開示書類の一覧取得（書類種別・証券コード・提出者名等でフィルタリング） -- 書類のダウンロード（PDF はそのまま、XBRL / CSV / 英文 / 添付資料は ZIP アーカイブ） -- 財務 CSV データの構造化抽出（実験的機能） -- HTML 書類からのテキスト抽出（セクション指定対応） -- 13,000社以上の企業検索（名称・証券コード・EDINET コード・業種） -- 企業の提出書類一覧の取得 -- AI エージェント向けの CLI スキーマ自己記述機能 +- **構造化出力**: stdout は常に JSON（`--format table` で人間向けテーブル） +- **決定論的な終了コード**: 自動化・エラーハンドリングが容易 +- **スキーマ自己記述**: `schema` コマンドで全機能を機械可読形式で取得 +- **財務データ抽出**: BS/PL/CF の構造化抽出と ROE・ROA 等の派生指標自動計算 +- **ローカルキャッシュ**: API レスポンスを自動キャッシュし不要なリクエストを削減 ## インストール @@ -51,13 +91,13 @@ make build ## クイックスタート ```bash -# API キーを設定 +# API キーを設定（環境変数のみ。ファイルには保存されない） export EDINET_API_KEY="your-api-key" # 今日の開示書類を一覧表示 edinet-cli doc list --date 2026-03-31 -# 有価証券報告書のみを絞り込み +# 有価証券報告書のみに絞り込み edinet-cli doc list --date 2026-03-31 --doc-type 120 # 企業を検索 @@ -65,21 +105,26 @@ edinet-cli company search トヨタ # 書類をPDFでダウンロード edinet-cli doc get S100ABCD --type pdf + +# 企業の財務サマリーを複数期間取得 +edinet-cli company financials 7203 --periods 3 --summary-only ``` +--- + ## コマンドリファレンス ### グローバルフラグ | フラグ | 型 | デフォルト | 説明 | |--------|------|-----------|------| -| `--format` | string | `json` | 出力形式（`json` または `table`） | +| `--format` | string | `json` | 出力形式（`json` / `table`） | | `--debug` | bool | `false` | デバッグ出力を stderr に表示 | | `--no-cache` | bool | `false` | ローカルキャッシュをバイパス | --- -### `doc list` — 開示書類の一覧取得 +### `doc list` --- 開示書類の一覧取得 日付または期間を指定して開示書類を一覧取得します。 @@ -89,6 +134,9 @@ edinet-cli doc list --date 2025-06-20 # 期間指定（有価証券報告書のみ） edinet-cli doc list --from 2025-06-01 --to 2025-06-30 --doc-type 120 + +# 提出者名と書類説明でフィルタ +edinet-cli doc list --date 2025-06-20 --filer-name トヨタ --doc-description 有価証券報告書 ``` | フラグ | 型 | 説明 | @@ -96,15 +144,16 @@ edinet-cli doc list --from 2025-06-01 --to 2025-06-30 --doc-type 120 | `--date` | string | 単一日付（YYYY-MM-DD）。`--from`/`--to` と排他 | | `--from` | string | 期間の開始日（`--to` と同時に指定） | | `--to` | string | 期間の終了日（`--from` と同時に指定） | -| `--doc-type` | string | 書類種別コードでフィルタ | -| `--sec-code` | string | 証券コードでフィルタ | +| `--doc-type` | string | 書類種別コードでフィルタ（例: `120`=有価証券報告書） | +| `--sec-code` | string | 証券コードでフィルタ（例: `72030`） | | `--edinet-code` | string | EDINET コードでフィルタ | | `--filer-name` | string | 提出者名で部分一致フィルタ | -| `--rate-limit` | int | リクエスト間隔（ミリ秒、デフォルト: 100） | +| `--doc-description` | string | 書類説明で部分一致フィルタ | +| `--rate-limit` | int | リクエスト間隔ミリ秒（デフォルト: 100） | --- -### `doc get` — 書類のダウンロード +### `doc get` --- 書類のダウンロード 指定した書類 ID のファイルをダウンロードします。 @@ -115,24 +164,40 @@ edinet-cli doc get S100ABCD --type csv --out ./data/ | フラグ | 型 | 必須 | デフォルト | 説明 | |--------|------|------|-----------|------| -| `--type` | string | **必須** | — | `pdf` / `xbrl`(zip) / `csv`(zip) / `attach`(zip) / `english`(zip) | -| `--out` | string | — | `.` | 出力ディレクトリ | +| `--type` | string | **必須** | --- | `pdf` / `xbrl`(zip) / `csv`(zip) / `attach`(zip) / `english`(zip) | +| `--out` | string | --- | `.` | 出力ディレクトリ | --- -### `doc data` — 財務データの抽出（実験的） +### `doc financial` --- 財務データの構造化抽出 -書類の CSV データを構造化して抽出します。 +書類の CSV データから BS（貸借対照表）/ PL（損益計算書）/ CF（キャッシュフロー計算書）を構造化抽出し、ROE・ROA 等の派生指標も自動計算します。 ```bash -edinet-cli doc data S100ABCD +# 全財務諸表を抽出 +edinet-cli doc financial S100ABCD + +# 損益計算書のみ +edinet-cli doc financial S100ABCD --statement pl + +# サマリー指標のみ（詳細行なし） +edinet-cli doc financial S100ABCD --summary-only + +# 単体財務諸表を優先 +edinet-cli doc financial S100ABCD --non-consolidated ``` +| フラグ | 型 | デフォルト | 説明 | +|--------|------|-----------|------| +| `--statement` | string | `all` | 財務諸表の種類: `bs` / `pl` / `cf` / `all` | +| `--non-consolidated` | bool | `false` | 単体（非連結）財務諸表を優先 | +| `--summary-only` | bool | `false` | サマリー指標のみ出力（詳細行を省略） | + --- -### `doc text` — テキストの抽出 +### `doc text` --- テキストの抽出 -HTML 書類からテキストを抽出します。セクション指定も可能です。 +HTML 書類からテキストを抽出します。セクション指定で特定の章のみ取得可能。 ```bash # 全テキストを抽出 @@ -156,7 +221,7 @@ edinet-cli doc text --list-sections |-----|--------------| | `business` | 事業の内容 | | `risk` | 事業等のリスク | -| `mda` | 経営者による財政状態 | +| `mda` | 経営者による財政状態・経営成績等の状況 | | `governance` | コーポレート・ガバナンス | | `financial` | 財務諸表 | | `employees` | 従業員の状況 | @@ -167,14 +232,24 @@ edinet-cli doc text --list-sections --- -### `company search` — 企業検索 +### `doc data` --- 財務データ抽出（実験的、非推奨） + +> **注意:** `doc financial` の利用を推奨します。`doc data` は後方互換のために残されています。 + +```bash +edinet-cli doc data S100ABCD +``` + +--- + +### `company search` --- 企業検索 -EDINET コードリストから企業を検索します。名称・証券コード・EDINET コードで検索可能です。 +EDINET コードリスト（13,000社以上）から企業を検索します。名称・証券コード・EDINET コードで検索可能。 ```bash edinet-cli company search トヨタ edinet-cli company search 7203 -edinet-cli company search E00010 --industry 自動車 +edinet-cli company search トヨタ --industry 自動車 ``` | フラグ | 型 | 説明 | @@ -183,9 +258,9 @@ edinet-cli company search E00010 --industry 自動車 --- -### `company filings` — 企業の提出書類一覧 +### `company filings` --- 企業の提出書類一覧 -指定した企業の提出書類を一覧取得します。証券コードまたは EDINET コードで指定できます。 +指定した企業の提出書類を一覧取得します。証券コードまたは EDINET コードで指定。 ```bash edinet-cli company filings 7203 --doc-type 120 --limit 5 @@ -194,37 +269,60 @@ edinet-cli company filings E00010 --from 2025-01-01 --to 2025-03-31 | フラグ | 型 | デフォルト | 説明 | |--------|------|-----------|------| -| `--doc-type` | string | — | 書類種別コードでフィルタ | +| `--doc-type` | string | --- | 書類種別コードでフィルタ | | `--from` | string | 365日前 | 期間の開始日 | | `--to` | string | 今日 | 期間の終了日 | | `--limit` | int | `0` | 最大件数（0=無制限） | --- -### `company update` — EDINET コードリストの更新 +### `company financials` --- 複数期間の財務データ取得 -EDINET コードリスト（企業マスタ）をダウンロードしてキャッシュを更新します。 +企業コード（証券コード・EDINET コード・企業名）を指定して、複数決算期の財務データを一括取得します。内部で有価証券報告書の検索・ダウンロード・抽出を自動で行います。 ```bash -edinet-cli company update +# 直近3期分の全財務諸表 +edinet-cli company financials 7203 + +# 直近5期分の損益計算書サマリー +edinet-cli company financials 7203 --periods 5 --statement pl --summary-only + +# 企業名でも指定可能 +edinet-cli company financials トヨタ --periods 3 ``` +| フラグ | 型 | デフォルト | 説明 | +|--------|------|-----------|------| +| `--periods` | int | `3` | 取得する決算期数（1-10） | +| `--statement` | string | `all` | 財務諸表の種類: `bs` / `pl` / `cf` / `all` | +| `--non-consolidated` | bool | `false` | 単体（非連結）財務諸表を優先 | +| `--summary-only` | bool | `false` | サマリー指標のみ出力 | + --- -### `schema` — CLI スキーマの自己記述 +### `company update` --- EDINET コードリストの更新 -AI エージェントが CLI の機能を自動的に把握するための機械可読メタデータを出力します。 +EDINET コードリスト（企業マスタ）をダウンロードしてキャッシュを更新します。 ```bash -# 全コマンドのフラグ・例をJSON で取得 -edinet-cli schema commands +edinet-cli company update +``` + +--- -# 書類種別コード一覧 -edinet-cli schema doc-types +### `schema` --- CLI メタデータの自己記述 -# テキスト抽出セクション一覧 -edinet-cli schema sections -``` +AIエージェントが CLI の全機能を自動把握するための機械可読メタデータ。 + +| サブコマンド | 説明 | +|-------------|------| +| `schema commands` | 全コマンドのフラグ・型・必須/任意・使用例 | +| `schema doc-types` | 書類種別コード一覧（42種） | +| `schema sections` | テキスト抽出セクション一覧 | +| `schema financial-elements` | 財務 XBRL 要素マッピング（BS/PL/CF 各勘定科目） | +| `schema derived-metrics` | 派生財務指標と計算式（ROE, ROA, FCF 等 9指標） | + +--- ## 設定 @@ -232,51 +330,53 @@ edinet-cli schema sections | 変数名 | 必須 | 説明 | |--------|------|------| -| `EDINET_API_KEY` | **必須** | EDINET API のサブスクリプションキー。ディスクには保存されません | -| `EDINET_CONFIG_DIR` | — | 設定ディレクトリのパス（デフォルト: `~/.config/edinet-cli`） | -| `EDINET_CACHE_DIR` | — | キャッシュディレクトリのパス（デフォルト: `~/.cache/edinet-cli`） | +| `EDINET_API_KEY` | **必須** | EDINET API サブスクリプションキー。ディスクには保存されない | +| `EDINET_CONFIG_DIR` | --- | 設定ディレクトリ（デフォルト: `~/.config/edinet-cli`） | +| `EDINET_CACHE_DIR` | --- | キャッシュディレクトリ（デフォルト: `~/.cache/edinet-cli`） | ### キャッシュ -API レスポンスは自動的にローカルにキャッシュされます： - -- 書類一覧: 過去日は24時間、当日は5分間 -- EDINET コードリスト: 7日間 +API レスポンスは自動キャッシュされます: -キャッシュを無視する場合は `--no-cache` フラグを使用してください。 +- **書類一覧**: 過去日は24時間、当日は5分間 +- **EDINET コードリスト**: 7日間 -## AI エージェント連携 +`--no-cache` でキャッシュをバイパスできます。 -`edinet-cli` は AI エージェント（Claude、ChatGPT 等）からの自律的な利用を想定して設計されています。 +--- -### 出力規約 +## 主な書類種別コード -- **stdout**: 常に構造化データ（JSON）。パース可能 -- **stderr**: エラー（JSON 形式）、進捗情報、デバッグ出力 -- **終了コード**: 自動化に対応した決定論的なコード体系 +| コード | 名称 | 用途 | +|--------|------|------| +| `120` | 有価証券報告書 | 年次の包括的開示（財務諸表・事業リスク等） | +| `130` | 訂正有価証券報告書 | 有価証券報告書の訂正 | +| `140` | 四半期報告書 | 四半期ごとの開示 | +| `160` | 半期報告書 | 半期の開示 | +| `180` | 臨時報告書 | 重要事象発生時の開示 | +| `350` | 大量保有報告書 | 5%以上の株式保有報告 | -| 終了コード | 意味 | -|-----------|------| -| 0 | 成功（部分成功を含む） | -| 1 | 一般エラー | -| 2 | バリデーションエラー（引数不正等） | -| 3 | 認証エラー（API キー未設定・無効） | -| 4 | API エラー（400/404/500） | +全42種のコード一覧は `edinet-cli schema doc-types` で取得できます。 -### スキーマによる自己発見 +## 派生財務指標 -AI エージェントは `schema` コマンドで CLI の全機能を事前に把握できます： +`doc financial` / `company financials` が自動計算する指標: -```bash -# 利用可能なコマンド・フラグ・使用例を取得 -edinet-cli schema commands +| 指標 | 計算式 | +|------|--------| +| `gross_margin` | 売上総利益 / 売上高 | +| `operating_margin` | 営業利益 / 売上高 | +| `net_margin` | 当期純利益 / 売上高 | +| `roe` | 当期純利益 / 自己資本 | +| `roa` | 当期純利益 / 総資産 | +| `equity_ratio` | 自己資本 / 総資産 | +| `current_ratio` | 流動資産 / 流動負債 | +| `fcf` | 営業CF + 投資CF | +| `debt_to_equity` | 有利子負債 / 自己資本 | -# 書類種別コードのマッピングを取得 -edinet-cli schema doc-types +全指標の詳細は `edinet-cli schema derived-metrics` で取得できます。 -# テキスト抽出可能なセクションを確認 -edinet-cli schema sections -``` +--- ## アーキテクチャ @@ -288,9 +388,10 @@ internal/ config/ 環境変数ベースの設定読み込み company/ EDINET コードリスト & 企業検索 extract/ ZIP / CSV / HTML の抽出・パース + financial/ 財務諸表パーサー（BS/PL/CF 抽出 & 派生指標計算） output/ JSON / テーブルフォーマッタ - service/ ビジネスロジック層（書類一覧・ダウンロード・企業検索） - schema/ CLI 自己記述データ（コマンド・書類種別・セクション） + service/ ビジネスロジック層（書類一覧・ダウンロード・企業検索・財務分析） + schema/ CLI 自己記述データ（コマンド・書類種別・セクション・財務要素） testutil/ テスト用共通ヘルパー（httptest モック） ```