ncli

Agent-native CLI for Naver Open APIs.

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

https://github.com/user-attachments/assets/c5776c61-b504-4aaa-bb08-591d4a95c4a1

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