@kiyeonjeon21/ncli 0.1.1 → 0.1.2

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/package.json

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