ncli

Agent-native CLI for Naver Open APIs.

Unofficial CLI for Naver Open APIs. Not affiliated with NAVER Corp.

ncli-demo.mp4

---

Why ncli?

Naver Open APIs have no official CLI. Existing tools are either MCP servers (high token cost, 72% reliability) or single-purpose scripts.

ncli is designed for AI agents first — structured JSON output, runtime schema introspection, input hardening, and safety rails — following the agentic-cli-guide principles.

	CLI (ncli)	MCP
Token cost	1x	10-32x
Reliability	100%	~72%
Startup	Instant	Protocol negotiation
Context overhead	Minimal	43+ tool schemas injected

---

Table of Contents

• Install
• Setup
• Usage
  • Search
  • DataLab
  • CAPTCHA
  • Schema Introspection
• Agent-First Design
• Rate Limits
• Configuration
• Development
• Troubleshooting
• Contributing
• License

---

Install

npm install -g @kiyeonjeon21/ncli

Or via curl (includes interactive setup):

curl -fsSL https://kiyeonjeon21.github.io/naver-cli/install | bash

Requires Node.js 18+.

Setup

Register an application at developers.naver.com and run:

ncli init

This prompts for your Client ID and Client Secret, then saves them to ~/.ncli/.env.

Usage

Search

# 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

# 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

# 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

# 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

ncli auth status       # Check authentication
ncli context           # Print CONTEXT.md for agents
ncli --version         # Show version
ncli --help            # Show help

Agent-First Design

Feature	Flag	Purpose
JSON output	--output json (default)	Machine-readable output
NDJSON streaming	--output ndjson	Line-by-line streaming
Field masks	--fields "title,link"	Reduce token usage
Dry-run	--dry-run	Validate without executing
Sanitize	--sanitize	Filter prompt injection
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 results
Context	ncli context	Inject CONTEXT.md into agent

Rate Limits

API	Limit
Search (all 13 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

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
npm run build                        # compile TypeScript

Troubleshooting

Problem	Solution
AUTH_REQUIRED	Run ncli init or set NAVER_CLIENT_ID and NAVER_CLIENT_SECRET
HTTP_400 on DataLab	endDate must not be in the future
HTTP_429 rate limited	Wait until daily limit resets (midnight KST)
Old version after install	Run npm uninstall -g naver-cli to remove legacy package
Scope Status Invalid	Check API permissions at developers.naver.com/apps

Contributing

See CONTRIBUTING.md for development setup, project structure, and release flow.

License

MIT