@kiyeonjeon21/ncli 0.1.1 → 0.1.3

package/CONTEXT.md

@@ -55,7 +55,7 @@ naver search blog "AI" --fields "title,link,description" --output json
 naver search news --json '{"query":"AI","display":5,"sort":"date"}'
 
 # NDJSON for streaming
-naver search shop "노트북" --output ndjson --fields "title,lprice,mallName"
+naver search shop "laptop" --output ndjson --fields "title,lprice,mallName"
 ```
 
 ### DataLab
@@ -65,14 +65,14 @@ naver datalab trend --json '{
   "startDate":"2026-01-01",
   "endDate":"2026-04-01",
   "timeUnit":"month",
-  "keywordGroups":[{"groupName":"AI","keywords":["인공지능","AI"]}]
+  "keywordGroups":[{"groupName":"AI","keywords":["artificial intelligence","AI"]}]
 }'
 ```
 
 ### Dry-run
 
 ```bash
-naver --dry-run search blog "테스트"
+naver --dry-run search blog "test"
 ```
 
 ## Error Handling

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kiyeon Jeon
+
+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,180 @@
+# ncli
+
+Agent-native CLI for Naver Open APIs.
+
+> Unofficial CLI for Naver Open APIs. Not affiliated with NAVER Corp.
+
+## Install
+
+```bash
+npm install -g @kiyeonjeon21/ncli
+```
+
+Or via curl (includes interactive setup):
+
+```bash
+curl -fsSL https://kiyeonjeon21.github.io/naver-cli/install | bash
+```
+
+Requires Node.js 18+.
+
+## Setup
+
+Register an application at [developers.naver.com](https://developers.naver.com/apps/) and run:
+
+```bash
+ncli init
+```
+
+This prompts for your Client ID and Client Secret, then saves them to `~/.ncli/.env`.
+
+## Usage
+
+### Search
+
+```bash
+# Blog search with field mask
+ncli search blog "AI" --fields "title,link,description"
+
+# News sorted by date
+ncli search news "semiconductor" --sort date --display 5
+
+# Shopping search as JSON payload
+ncli search shop --json '{"query":"macbook","display":3,"sort":"dsc"}' --fields "title,lprice,mallName"
+
+# Paginate through results
+ncli search blog "TypeScript" --page-all --max-results 50 --output ndjson
+
+# Pipe JSON from stdin
+echo '{"query":"AI","display":5}' | ncli search blog --json -
+```
+
+Available search types: `blog`, `news`, `web`, `image`, `book`, `cafe`, `kin`, `encyclopedia`, `shop`, `local`, `errata`, `adult`, `doc`
+
+### DataLab
+
+```bash
+# Search keyword trend
+ncli datalab trend --json '{
+  "startDate": "2026-01-01",
+  "endDate": "2026-04-01",
+  "timeUnit": "month",
+  "keywordGroups": [
+    {"groupName": "AI", "keywords": ["AI", "artificial intelligence"]}
+  ]
+}'
+
+# Shopping category trend
+ncli datalab shopping --json '{
+  "startDate": "2026-01-01",
+  "endDate": "2026-04-01",
+  "timeUnit": "month",
+  "category": [{"name": "laptop", "param": ["50000832"]}]
+}'
+```
+
+### CAPTCHA
+
+```bash
+# Issue image CAPTCHA key
+ncli captcha image key
+
+# Download CAPTCHA image
+ncli captcha image download --key <KEY>
+
+# Verify user input
+ncli captcha image verify --key <KEY> --value <INPUT>
+
+# Voice CAPTCHA (same pattern)
+ncli captcha voice key
+```
+
+### Schema Introspection
+
+```bash
+# List available services
+ncli schema --list-services
+
+# List methods for a service
+ncli schema --list-methods search
+
+# Inspect a specific method
+ncli schema search.blog
+
+# Or use --describe on any command
+ncli search blog --describe
+```
+
+### Other Commands
+
+```bash
+# Check auth status
+ncli auth status
+
+# Print CONTEXT.md for agent consumption
+ncli context
+
+# Show version
+ncli --version
+```
+
+## Agent-First Design
+
+ncli is built for AI agents following the [agentic-cli-guide](https://github.com/kiyeonjeon21/agentic-cli-guide) principles:
+
+| Feature | Flag | Purpose |
+|---------|------|---------|
+| JSON output | `--output json` (default) | Machine-readable output |
+| NDJSON streaming | `--output ndjson` | Line-by-line streaming for large results |
+| Field masks | `--fields "title,link"` | Reduce token usage |
+| Dry-run | `--dry-run` | Validate without executing |
+| Sanitize | `--sanitize` | Filter prompt injection in API responses |
+| Schema | `--describe` / `ncli schema` | Runtime API introspection |
+| Stdin | `--json -` | Pipe JSON payloads |
+| File input | `--json @payload.json` | Read JSON from file |
+| Pagination | `--page-all --max-results N` | Auto-paginate search results |
+| Context | `ncli context` | Inject CONTEXT.md into agent context |
+
+### Why CLI over MCP?
+
+| Metric | CLI | MCP |
+|--------|-----|-----|
+| Token cost | 1x | 10-32x |
+| Reliability | 100% | ~72% |
+| Startup | Instant | Protocol negotiation |
+
+CLI is the pragmatic choice for agent tooling. MCP servers for Naver APIs [already exist](https://github.com/isnow890/naver-search-mcp) for environments that need them.
+
+## Rate Limits
+
+| API | Limit |
+|-----|-------|
+| Search (all types) | 25,000/day |
+| DataLab (trend) | 1,000/day |
+| DataLab (shopping) | 1,000/day |
+| CAPTCHA | 1,000/day |
+
+## Configuration
+
+Credentials are loaded in this priority:
+
+1. Environment variables (`NAVER_CLIENT_ID`, `NAVER_CLIENT_SECRET`)
+2. Project `.env` file (via dotenv)
+3. Global `~/.ncli/.env` (set by `ncli init`)
+
+## Development
+
+```bash
+git clone https://github.com/kiyeonjeon21/naver-cli.git
+cd naver-cli
+npm install
+cp .env.example .env  # add your credentials
+
+npm run dev -- search blog "test"   # run in dev mode
+npm test                             # run tests (58 tests)
+npm run build                        # compile TypeScript
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 import "dotenv/config";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 import { Command } from "commander";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 import { searchCommand } from "./commands/search.js";
 import { datalabCommand } from "./commands/datalab.js";
 import { authCommand } from "./commands/auth.js";
@@ -12,7 +17,7 @@ const program = new Command();
 program
     .name("ncli")
     .description("Agent-native CLI for Naver Open APIs")
-    .version("0.1.0")
+    .version(pkg.version)
     .option("--output <format>", "output format: json, ndjson, table", "json")
     .option("--fields <fields>", "comma-separated field mask")
     .option("--dry-run", "validate without executing")

package/dist/commands/datalab.js

@@ -13,7 +13,7 @@ datalabCommand
     .option("--describe", "show API schema for this command (no execution)")
     .addHelpText("after", `
 Examples:
-  ncli datalab trend --json '{"startDate":"2026-01-01","endDate":"2026-04-01","timeUnit":"month","keywordGroups":[{"groupName":"AI","keywords":["AI","인공지능"]}]}'
+  ncli datalab trend --json '{"startDate":"2026-01-01","endDate":"2026-04-01","timeUnit":"month","keywordGroups":[{"groupName":"AI","keywords":["AI","artificial intelligence"]}]}'
 
 Schema: ncli schema datalab.trend`)
     .action(async (opts) => {
@@ -59,7 +59,7 @@ datalabCommand
     .option("--describe", "show API schema for this command (no execution)")
     .addHelpText("after", `
 Examples:
-  ncli datalab shopping --json '{"startDate":"2026-01-01","endDate":"2026-04-01","timeUnit":"month","category":[{"name":"노트북","param":["50000832"]}]}'
+  ncli datalab shopping --json '{"startDate":"2026-01-01","endDate":"2026-04-01","timeUnit":"month","category":[{"name":"laptop","param":["50000832"]}]}'
 
 Schema: ncli schema datalab.shopping`)
     .action(async (opts) => {

package/dist/commands/init.js

@@ -3,13 +3,49 @@ import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
 import { createInterface } from "readline";
 import { NCLI_DIR, NCLI_ENV_PATH, loadConfig } from "../core/config.js";
 import { printJson } from "../core/output.js";
-function prompt(question) {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
+function prompt(question, mask = false) {
     return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.trim());
-        });
+        process.stderr.write(question);
+        if (!mask) {
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            rl.question("", (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+            return;
+        }
+        // Masked input
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf-8");
+        let input = "";
+        const onData = (ch) => {
+            if (ch === "\r" || ch === "\n") {
+                stdin.removeListener("data", onData);
+                if (stdin.isTTY)
+                    stdin.setRawMode(wasRaw ?? false);
+                stdin.pause();
+                process.stderr.write("\n");
+                resolve(input.trim());
+            }
+            else if (ch === "\x7f" || ch === "\b") {
+                if (input.length > 0) {
+                    input = input.slice(0, -1);
+                    process.stderr.write("\b \b");
+                }
+            }
+            else if (ch === "\x03") {
+                process.exit(1);
+            }
+            else {
+                input += ch;
+                process.stderr.write("*");
+            }
+        };
+        stdin.on("data", onData);
     });
 }
 export const initCommand = new Command("init")
@@ -39,12 +75,12 @@ export const initCommand = new Command("init")
     process.stderr.write("  Register an app at: https://developers.naver.com/apps/\n");
     process.stderr.write("  Select APIs: Search, DataLab, etc.\n");
     process.stderr.write("  Web service URL: http://localhost\n\n");
-    const clientId = await prompt("  Client ID: ");
+    const clientId = await prompt("  Client ID: ", true);
     if (!clientId) {
         process.stderr.write("  Aborted — no Client ID provided.\n");
         process.exit(1);
     }
-    const clientSecret = await prompt("  Client Secret: ");
+    const clientSecret = await prompt("  Client Secret: ", true);
     if (!clientSecret) {
         process.stderr.write("  Aborted — no Client Secret provided.\n");
         process.exit(1);

package/dist/commands/search.js

@@ -24,18 +24,18 @@ const SEARCH_BASE_URL = "https://openapi.naver.com/v1/search";
 const SEARCH_EXAMPLES = {
     blog: `  ncli search blog "AI" --fields "title,link,description"
   ncli search blog --json '{"query":"AI","display":5,"sort":"date"}'`,
-    news: `  ncli search news "반도체" --fields "title,link,pubDate"`,
+    news: `  ncli search news "semiconductor" --fields "title,link,pubDate"`,
     web: `  ncli search web "TypeScript" --fields "title,link,description"`,
-    image: `  ncli search image "제주도" --display 5`,
-    book: `  ncli search book "인공지능" --fields "title,author,publisher,isbn"`,
-    cafe: `  ncli search cafe "맛집" --fields "title,link,cafename"`,
-    kin: `  ncli search kin "프로그래밍" --sort count`,
-    encyclopedia: `  ncli search encyclopedia "양자역학" --fields "title,link,description"`,
-    shop: `  ncli search shop "노트북" --fields "title,lprice,mallName" --sort dsc`,
-    local: `  ncli search local "강남 맛집" --fields "title,address,telephone"`,
-    errata: `  ncli search errata "오타확인"`,
-    adult: `  ncli search adult "검색어"`,
-    doc: `  ncli search doc "인공지능 논문" --fields "title,link,description"`,
+    image: `  ncli search image "Jeju" --display 5`,
+    book: `  ncli search book "artificial intelligence" --fields "title,author,publisher,isbn"`,
+    cafe: `  ncli search cafe "restaurant" --fields "title,link,cafename"`,
+    kin: `  ncli search kin "programming" --sort count`,
+    encyclopedia: `  ncli search encyclopedia "quantum mechanics" --fields "title,link,description"`,
+    shop: `  ncli search shop "laptop" --fields "title,lprice,mallName" --sort dsc`,
+    local: `  ncli search local "Gangnam restaurant" --fields "title,address,telephone"`,
+    errata: `  ncli search errata "typo check"`,
+    adult: `  ncli search adult "keyword"`,
+    doc: `  ncli search doc "AI research paper" --fields "title,link,description"`,
 };
 const API_TYPE_MAP = {
     encyclopedia: "encyc",

package/dist/core/output.js

@@ -24,12 +24,28 @@ export function applyFieldMask(data, fields) {
     }
     return result;
 }
+function stripHtml(value) {
+    if (typeof value === "string") {
+        return value.replace(/<\/?[^>]+(>|$)/g, "");
+    }
+    if (Array.isArray(value)) {
+        return value.map(stripHtml);
+    }
+    if (typeof value === "object" && value !== null) {
+        const result = {};
+        for (const [k, v] of Object.entries(value)) {
+            result[k] = stripHtml(v);
+        }
+        return result;
+    }
+    return value;
+}
 export function printJson(data) {
-    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    process.stdout.write(JSON.stringify(stripHtml(data), null, 2) + "\n");
 }
 export function printNdjson(items) {
     for (const item of items) {
-        process.stdout.write(JSON.stringify(item) + "\n");
+        process.stdout.write(JSON.stringify(stripHtml(item)) + "\n");
     }
 }
 export function printOutput(data, format, fields) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiyeonjeon21/ncli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Agent-native CLI for Naver Open APIs",
   "type": "module",
   "bin": {

package/skills/datalab.md

@@ -31,8 +31,8 @@ naver datalab trend --json '{
   "endDate": "2026-04-01",
   "timeUnit": "month",
   "keywordGroups": [
-    {"groupName": "AI", "keywords": ["인공지능", "AI"]},
-    {"groupName": "블록체인", "keywords": ["블록체인", "blockchain"]}
+    {"groupName": "AI", "keywords": ["artificial intelligence", "AI"]},
+    {"groupName": "blockchain", "keywords": ["blockchain", "blockchain"]}
   ]
 }'
 ```
@@ -45,7 +45,7 @@ naver datalab shopping --json '{
   "endDate": "2026-04-01",
   "timeUnit": "month",
   "category": [
-    {"name": "노트북", "param": ["50000832"]}
+    {"name": "laptop", "param": ["50000832"]}
   ]
 }'
 ```
@@ -57,7 +57,7 @@ naver datalab trend --json '{
   "startDate": "2026-01-01",
   "endDate": "2026-04-01",
   "timeUnit": "week",
-  "keywordGroups": [{"groupName": "test", "keywords": ["테스트"]}],
+  "keywordGroups": [{"groupName": "test", "keywords": ["test"]}],
   "device": "mo",
   "gender": "f",
   "ages": ["20", "30"]

package/skills/search.md

@@ -29,7 +29,7 @@ export NAVER_CLIENT_SECRET="your-client-secret"
 ### Quick search
 
 ```bash
-naver search blog "검색어" --fields "title,link,description"
+naver search blog "keyword" --fields "title,link,description"
 ```
 
 ### Paginated search
@@ -45,7 +45,7 @@ naver search news "AI" --display 10 --start 11 --fields "title,link,pubDate"
 ### JSON payload
 
 ```bash
-naver search shop --json '{"query":"맥북","display":5,"sort":"dsc"}' \
+naver search shop --json '{"query":"macbook","display":5,"sort":"dsc"}' \
   --fields "title,lprice,hprice,mallName"
 ```