viruagent-cli 0.3.6 → 0.4.0

package/README.ko.md

@@ -18,25 +18,33 @@
   <a href="README.ko.md"><img src="https://img.shields.io/badge/한국어-red" alt="Korean"></a>
 </p>
 
-**AI 에이전트가 블로그를 쓰고, 태그를 만들고, 발행까지 자동으로 처리하는 CLI 도구**
+**AI 에이전트가 블로그 발행부터 SNS 활동까지 자동으로 처리하는 CLI 도구**
 
 사람이 아닌 **AI 에이전트를 위해** 설계되었습니다.
 
+## 지원 플랫폼
+
+| 플랫폼 | 로그인 | 주요 기능 | 가이드 |
+|--------|--------|----------|--------|
+| **Tistory** | Playwright (카카오) | 글 발행, 임시저장, 카테고리, 이미지 업로드 | [가이드](docs/guide-tistory.md) |
+| **Naver Blog** | Playwright (네이버) | 글 발행, 카테고리, SE Editor, 이미지 업로드 | [가이드](docs/guide-naver.md) |
+| **Instagram** | HTTP (브라우저 불필요) | 좋아요, 댓글, 팔로우, 포스팅, 프로필, 피드 | [가이드](docs/guide-instagram.md) |
+
 ## 동작 방식
 
-**CLI + 스킬 기반**으로 작동합니다. CLI 자체는 인터페이스만 담당하고, CLI 호출 흐름, 글 양식 등 스킬 파일(`viruagent.md`)이 AI 에이전트에게 지시합니다.
+**CLI + 스킬 기반**으로 작동합니다. CLI 자체는 인터페이스만 담당하고, 스킬 파일(`viruagent.md`)이 AI 에이전트에게 워크플로우를 지시합니다.
 
 ```
 사용자: "블로그 써줘"
   → 스킬이 에이전트에게 워크플로우 지시
     → 에이전트가 CLI를 호출 (로그인, 카테고리 조회, 발행 등)
 
-사용자: /viruagent "글 써줘"
-  → 스킬 직접 호출
+사용자: "@username 게시물 전부 좋아요하고 댓글 달아줘"
+  → 에이전트가 Instagram 프로바이더 사용 (로그인, listPosts, like, analyzePost, comment)
 ```
 
-- **스킬 파일**: 에이전트가 무엇을, 어떤 순서로 할지 정의 (글 구조, 태그 규칙, 이미지 설정 등)
-- **CLI**: 스킬의 지시를 받아 실제 작업 수행 (로그인, API 호출, 브라우저 자동화)
+- **스킬 파일**: 에이전트가 무엇을, 어떤 순서로 할지 정의
+- **CLI**: 스킬의 지시를 받아 실제 작업 수행
 - **에이전트**: 스킬을 읽고 CLI를 조합하여 자율적으로 실행
 - **커스텀**: 스킬 파일을 직접 수정하여 원하는 대로 동작하도록 설정 가능
 
@@ -44,7 +52,7 @@
 
 ![viru_install](https://github.com/user-attachments/assets/35efb57f-fada-44c0-8dd4-6d586ef33a7c)
 
-아래 내용을 AI 에이전트에게 그대로 복사해서 보여주세요. (AI 에이전트 대상이므로 영어로 작성되어 있습니다)
+아래 내용을 AI 에이전트에게 그대로 복사해서 보여주세요.
 
 ```
 You are installing viruagent-cli, a blog publishing CLI tool. Follow these steps in order.
@@ -67,42 +75,44 @@ Tell the user that viruagent-cli installation is complete.
 ### Tistory
 
 ```bash
-# Chrome 세션 임포트 (ID/PW 불필요, macOS & Windows)
-npx viruagent-cli login --from-chrome
-
-# 특정 Chrome 프로필 사용
-npx viruagent-cli login --from-chrome --profile "Profile 2"
-
-# 기존 카카오 로그인 (ID/PW 필요)
-npx viruagent-cli login --username <id> --password <pw> --headless
+npx viruagent-cli login --provider tistory --username <카카오 ID> --password <비밀번호> --headless
 ```
+> "티스토리 로그인해줘" — 에이전트가 알아서 처리
 
 ### Naver Blog
 
 ```bash
-# Chrome 세션 임포트 (권장)
-npx viruagent-cli login --provider naver --from-chrome
+npx viruagent-cli login --provider naver --username <네이버 ID> --password <비밀번호>
+```
+> "네이버 블로그 로그인해줘" — 에이전트가 알아서 처리
 
-# 수동 로그인 (브라우저에서 직접 로그인)
-npx viruagent-cli login --provider naver --manual
+### Instagram
 
-# 자동 로그인 (ID/PW)
-npx viruagent-cli login --provider naver --username <id> --password <pw>
+```bash
+npx viruagent-cli login --provider insta --username <인스타 ID> --password <비밀번호>
 ```
-
-> [!TIP]
-> `--from-chrome`은 Chrome에서 직접 쿠키를 추출합니다 — macOS Keychain 또는 Windows DPAPI를 사용하며, CDP 폴백도 지원합니다. 브라우저 실행 없이, 2FA 없이, 1초 내 완료됩니다.
+> "인스타 로그인해줘" — 에이전트가 알아서 처리
+>
+> 전체 API 레퍼런스와 rate limit 규칙은 [Instagram 가이드](docs/guide-instagram.md)를 참고하세요.
 
 ## 사용법
 
 | 이렇게 말하면 | 에이전트가 알아서 |
 |---|---|
-| "블로그 써줘" | 로그인 → 카테고리 → 글 작성 → 태그 → 발행 |
+| "티스토리에 블로그 써줘" | 로그인 → 카테고리 → 글 작성 → 태그 → 발행 |
+| "네이버에 글 올려줘" | 네이버 로그인 → 카테고리 → 발행 |
 | "임시저장해줘" | 같은 흐름, 발행 대신 임시저장 |
 | "최근 글 보여줘" | 최근 발행 글 목록 조회 |
-| "카테고리 뭐 있어?" | 카테고리 목록 조회 |
+| "@user 게시물 전부 좋아요해줘" | 로그인 → listPosts → like (rate limit 자동 적용) |
+| "이 사람 피드 분석해서 댓글 달아줘" | analyzePost → AI 댓글 생성 → comment |
+| "@user 팔로우해줘" | 로그인 → follow (딜레이 자동 적용) |
+| "인스타 rate limit 확인해줘" | rate-limit-status → 카운터 표시 |
+
+## 플랫폼별 가이드
 
-자세한 사용법이나 커스터마이징은 에이전트에게 물어보면 안내해줍니다.
+- **[Tistory 가이드](docs/guide-tistory.md)** — 블로그 발행, 이미지 업로드, 카테고리
+- **[Naver Blog 가이드](docs/guide-naver.md)** — SE Editor, 블로그 발행, 이미지 업로드
+- **[Instagram 가이드](docs/guide-instagram.md)** — 18개 API 메서드, rate limit 규칙, AI 댓글
 
 ## 지원 환경
 
@@ -112,21 +122,15 @@ npx viruagent-cli login --provider naver --username <id> --password <pw>
 | bash 실행 가능한 모든 AI 에이전트 | 지원 |
 | Node.js | >= 18 |
 
-## 지원 플랫폼
-
-| 플랫폼 | 상태 |
-| --- | --- |
-| Tistory | 지원 |
-| Naver Blog | 지원 |
-
 ## 기술 스택
 
 | 영역 | 기술 |
 | --- | --- |
 | CLI 프레임워크 | Commander.js |
-| 브라우저 자동화 | Playwright (Chromium) |
-| 쿠키 복호화 | macOS Keychain + AES-128-CBC / Windows DPAPI + AES-256-GCM / CDP 폴백 |
+| 브라우저 자동화 | Playwright (Tistory, Naver만 사용) |
+| Instagram API | 순수 HTTP fetch (브라우저 불필요) |
 | 세션 관리 | JSON 파일 (`~/.viruagent-cli/`) |
+| Rate Limiting | 유저별 영속 카운터 + 랜덤 딜레이 |
 | 이미지 검색 | DuckDuckGo, Wikimedia Commons |
 | 네이버 에디터 | SE Editor 컴포넌트 모델 + RabbitWrite API |
 | 출력 형식 | JSON envelope (`{ ok, data }` / `{ ok, error, hint }`) |

package/README.md

@@ -18,10 +18,18 @@
   <a href="README.ko.md"><img src="https://img.shields.io/badge/한국어-red" alt="Korean"></a>
 </p>
 
-**A CLI tool where AI agents write, tag, and publish blog posts automatically.**
+**A CLI tool where AI agents write, publish, and engage across blog & social platforms automatically.**
 
 Designed not for humans, but for **AI agents**.
 
+## Supported Platforms
+
+| Platform | Login | Features | Guide |
+|----------|-------|----------|-------|
+| **Tistory** | Playwright (Kakao) | Publish, Draft, Categories, Image Upload | [Guide](docs/guide-tistory.md) |
+| **Naver Blog** | Playwright (Naver) | Publish, Categories, SE Editor, Image Upload | [Guide](docs/guide-naver.md) |
+| **Instagram** | HTTP (No Browser) | Like, Comment, Follow, Post, Profile, Feed, Rate Limit | [Guide](docs/guide-instagram.md) |
+
 ## How It Works
 
 Operates via **CLI + skill files**. The CLI handles the interface; the skill file (`viruagent.md`) instructs the AI agent on workflow, formatting, and rules.
@@ -31,13 +39,13 @@ User: "Write a blog post"
   → Skill instructs the agent on workflow
     → Agent calls CLI (login, list categories, publish, etc.)
 
-User: /viruagent "Write a post"
-  → Direct skill invocation
+User: "Like and comment on all posts from @username"
+  → Agent uses Instagram provider (login, listPosts, like, analyzePost, comment)
 ```
 
-- **Skill file**: Defines what to do and in what order (post structure, tag rules, image settings)
-- **CLI**: Executes tasks per skill instructions (login, API calls, browser automation)
-- **Agent**: Reads the skill and orchestrates CLI commands autonomously
+- **Skill file**: Defines what to do and in what order
+- **CLI**: Executes tasks per skill instructions
+- **Agent**: Reads the skill and orchestrates commands autonomously
 - **Custom**: Edit the skill file to customize behavior
 
 ## Quick Start
@@ -67,42 +75,44 @@ Tell the user that viruagent-cli installation is complete.
 ### Tistory
 
 ```bash
-# Import session from Chrome (no ID/PW needed, macOS & Windows)
-npx viruagent-cli login --from-chrome
-
-# Use a specific Chrome profile
-npx viruagent-cli login --from-chrome --profile "Profile 2"
-
-# Traditional Kakao login (ID/PW required)
-npx viruagent-cli login --username <id> --password <pw> --headless
+npx viruagent-cli login --provider tistory --username <kakao_id> --password <pw> --headless
 ```
+> "Login to Tistory" — Agent handles it automatically
 
 ### Naver Blog
 
 ```bash
-# Import session from Chrome (recommended)
-npx viruagent-cli login --provider naver --from-chrome
-
-# Manual login via browser
-npx viruagent-cli login --provider naver --manual
-
-# Auto login with credentials
 npx viruagent-cli login --provider naver --username <id> --password <pw>
 ```
+> "Login to Naver Blog" — Agent handles it automatically
 
-> [!TIP]
-> `--from-chrome` extracts cookies from Chrome directly — via macOS Keychain or Windows DPAPI, with CDP fallback. No browser launch, no 2FA — completes in under 1 second.
+### Instagram
+
+```bash
+npx viruagent-cli login --provider insta --username <id> --password <pw>
+```
+> "Login to Instagram" — Agent handles it automatically
+>
+> See the [Instagram Guide](docs/guide-instagram.md) for full API reference and rate limit rules.
 
 ## Usage
 
 | Say this | Agent handles |
 |---|---|
-| "Write a blog post" | Login → Categories → Draft → Tags → Publish |
+| "Write a blog post on Tistory" | Login → Categories → Draft → Tags → Publish |
+| "Post to Naver Blog" | Naver login → Categories → Publish |
 | "Save as draft" | Same flow, saves as draft instead |
 | "Show recent posts" | Lists recent published posts |
-| "What categories?" | Lists available categories |
+| "Like all posts from @user" | Login → listPosts → like (with rate limit) |
+| "Analyze and comment on @user's feed" | analyzePost → AI generates comment → comment |
+| "Follow @user" | Login → follow (with delay) |
+| "Check Instagram rate limit" | rate-limit-status → show counters |
 
-Ask the agent for detailed usage or customization help.
+## Platform Guides
+
+- **[Tistory Guide](docs/guide-tistory.en.md)** — Blog publishing, image upload, categories
+- **[Naver Blog Guide](docs/guide-naver.en.md)** — SE Editor, blog publishing, image upload
+- **[Instagram Guide](docs/guide-instagram.en.md)** — 18 API methods, rate limits, AI commenting
 
 ## Supported Environments
 
@@ -112,21 +122,15 @@ Ask the agent for detailed usage or customization help.
 | Any AI agent with bash access | Supported |
 | Node.js | >= 18 |
 
-## Supported Platforms
-
-| Platform | Status |
-| --- | --- |
-| Tistory | Supported |
-| Naver Blog | Supported |
-
 ## Tech Stack
 
 | Area | Tech |
 | --- | --- |
 | CLI Framework | Commander.js |
-| Browser Automation | Playwright (Chromium) |
-| Cookie Decryption | macOS Keychain + AES-128-CBC / Windows DPAPI + AES-256-GCM / CDP fallback |
+| Browser Automation | Playwright (Tistory, Naver only) |
+| Instagram API | Pure HTTP fetch (no browser) |
 | Session Management | JSON file (`~/.viruagent-cli/`) |
+| Rate Limiting | Per-user persistent counters with random delays |
 | Image Search | DuckDuckGo, Wikimedia Commons |
 | Naver Editor | SE Editor component model + RabbitWrite API |
 | Output Format | JSON envelope (`{ ok, data }` / `{ ok, error, hint }`) |

package/bin/index.js

@@ -18,7 +18,7 @@ program
 
 // Global options
 const addProviderOption = (cmd) =>
-  cmd.option('--provider <name>', 'Provider name (tistory or naver)', 'tistory');
+  cmd.option('--provider <name>', 'Provider name (tistory, naver, insta)', 'tistory');
 
 const addDryRunOption = (cmd) =>
   cmd.option('--dry-run', 'Validate params without executing', false);
@@ -49,8 +49,6 @@ loginCmd
   .option('--headless', 'Run browser in headless mode', false)
   .option('--manual', 'Use manual login mode', false)
   .option('--two-factor-code <code>', '2FA verification code')
-  .option('--from-chrome', 'Import session from Chrome browser', false)
-  .option('--profile <name>', 'Chrome profile name (default: Default)')
   .action((opts) => execute('login', opts));
 
 const publishCmd = program
@@ -104,6 +102,7 @@ const listPostsCmd = program
   .description('List recent posts');
 addProviderOption(listPostsCmd);
 listPostsCmd
+  .option('--username <username>', 'Target username (required for insta)')
   .option('--limit <n>', 'Number of posts to retrieve', '20')
   .action((opts) => execute('list-posts', opts));
 
@@ -132,6 +131,95 @@ const listProvidersCmd = program
   .description('List supported providers');
 listProvidersCmd.action((opts) => execute('list-providers', opts));
 
+// --- Instagram / SNS commands ---
+
+const getProfileCmd = program
+  .command('get-profile')
+  .description('Get user profile info');
+addProviderOption(getProfileCmd);
+getProfileCmd
+  .option('--username <username>', 'Target username')
+  .action((opts) => execute('get-profile', opts));
+
+const getFeedCmd = program
+  .command('get-feed')
+  .description('Get feed timeline');
+addProviderOption(getFeedCmd);
+getFeedCmd.action((opts) => execute('get-feed', opts));
+
+const likeCmd = program
+  .command('like')
+  .description('Like a post');
+addProviderOption(likeCmd);
+likeCmd
+  .option('--post-id <shortcode>', 'Post shortcode')
+  .action((opts) => execute('like', opts));
+
+const unlikeCmd = program
+  .command('unlike')
+  .description('Unlike a post');
+addProviderOption(unlikeCmd);
+unlikeCmd
+  .option('--post-id <shortcode>', 'Post shortcode')
+  .action((opts) => execute('unlike', opts));
+
+const commentCmd = program
+  .command('comment')
+  .description('Comment on a post');
+addProviderOption(commentCmd);
+commentCmd
+  .option('--post-id <shortcode>', 'Post shortcode')
+  .option('--text <text>', 'Comment text')
+  .action((opts) => execute('comment', opts));
+
+const followCmd = program
+  .command('follow')
+  .description('Follow a user');
+addProviderOption(followCmd);
+followCmd
+  .option('--username <username>', 'Target username')
+  .action((opts) => execute('follow', opts));
+
+const unfollowCmd = program
+  .command('unfollow')
+  .description('Unfollow a user');
+addProviderOption(unfollowCmd);
+unfollowCmd
+  .option('--username <username>', 'Target username')
+  .action((opts) => execute('unfollow', opts));
+
+const likeCommentCmd = program
+  .command('like-comment')
+  .description('Like a comment');
+addProviderOption(likeCommentCmd);
+likeCommentCmd
+  .option('--comment-id <id>', 'Comment ID')
+  .action((opts) => execute('like-comment', opts));
+
+const unlikeCommentCmd = program
+  .command('unlike-comment')
+  .description('Unlike a comment');
+addProviderOption(unlikeCommentCmd);
+unlikeCommentCmd
+  .option('--comment-id <id>', 'Comment ID')
+  .action((opts) => execute('unlike-comment', opts));
+
+const analyzePostCmd = program
+  .command('analyze-post')
+  .description('Analyze a post (thumbnail + caption + profile)');
+addProviderOption(analyzePostCmd);
+analyzePostCmd
+  .option('--post-id <shortcode>', 'Post shortcode')
+  .action((opts) => execute('analyze-post', opts));
+
+const rateLimitCmd = program
+  .command('rate-limit-status')
+  .description('Show current rate limit usage');
+addProviderOption(rateLimitCmd);
+rateLimitCmd.action((opts) => execute('rate-limit-status', opts));
+
+// --- Utility commands ---
+
 const installSkillCmd = program
   .command('install-skill')
   .description('Install viruagent skill for Claude Code / Codex')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "viruagent-cli",
-  "version": "0.3.6",
-  "description": "AI-agent-optimized CLI for blog publishing (Tistory, Naver)",
+  "version": "0.4.0",
+  "description": "AI-agent-optimized CLI for blog publishing (Tistory, Naver) and Instagram automation",
   "private": false,
   "type": "commonjs",
   "license": "MIT",
@@ -11,6 +11,7 @@
     "blog",
     "tistory",
     "naver",
+    "instagram",
     "publishing",
     "automation",
     "llm",

package/skills/viruagent-insta.md

@@ -0,0 +1,163 @@
+---
+name: viruagent-insta
+description: Instagram automation via viruagent-cli — like, comment, follow, post, analyze feed. Handles rate limits and bot detection avoidance.
+triggers:
+  - 인스타
+  - 인스타그램
+  - instagram
+  - insta
+  - 좋아요
+  - 댓글 달아
+  - 팔로우
+  - 언팔로우
+  - 피드
+  - like
+  - comment
+  - follow
+  - unfollow
+  - feed
+---
+
+# viruagent-insta — Instagram Automation Skill
+
+You are an Instagram automation agent using `viruagent-cli`. Always use `npx viruagent-cli` with `--provider insta`.
+
+## Step 1: Check authentication
+
+```bash
+npx viruagent-cli status --provider insta
+```
+
+If not logged in:
+
+```bash
+npx viruagent-cli login --provider insta --username <user> --password <pass>
+```
+
+Environment variables `INSTA_USERNAME` / `INSTA_PASSWORD` also work.
+
+## Step 2: Available commands
+
+### Profile & Feed
+
+```bash
+# Get user profile
+npx viruagent-cli get-profile --provider insta --username <username>
+
+# Get your feed timeline
+npx viruagent-cli get-feed --provider insta
+
+# List user's posts (with pagination)
+npx viruagent-cli list-posts --provider insta --username <username> --limit 20
+```
+
+### Engagement (auto rate-limit delays applied)
+
+```bash
+# Like a post
+npx viruagent-cli like --provider insta --post-id <shortcode>
+
+# Comment on a post
+npx viruagent-cli comment --provider insta --post-id <shortcode> --text "comment text"
+
+# Follow / Unfollow
+npx viruagent-cli follow --provider insta --username <username>
+npx viruagent-cli unfollow --provider insta --username <username>
+
+# Like / Unlike a comment
+npx viruagent-cli like-comment --provider insta --comment-id <id>
+npx viruagent-cli unlike-comment --provider insta --comment-id <id>
+```
+
+### Analyze & Smart Comment
+
+```bash
+# Analyze post (returns caption + thumbnail base64 + profile)
+npx viruagent-cli analyze-post --provider insta --post-id <shortcode>
+```
+
+Use `analyze-post` to get the thumbnail image, then visually analyze it to write contextual comments.
+
+### Publish
+
+```bash
+# Publish an image post (provide imageUrl or imagePath in code)
+# CLI does not have a direct publish command — use the Node.js API:
+```
+
+```javascript
+const insta = require('viruagent-cli/src/services/providerManager').createProviderManager().getProvider('insta');
+await insta.publish({ imageUrl: 'https://...', caption: 'My post' });
+```
+
+### Rate Limit
+
+```bash
+npx viruagent-cli rate-limit-status --provider insta
+```
+
+## Workflows
+
+### "Like all posts from @user"
+
+1. `list-posts --username <user> --limit 20`
+2. For each post: `like --post-id <shortcode>`
+3. Rate limit delays are automatic (20~40s between likes)
+
+### "Comment on all @user's posts"
+
+1. `list-posts --username <user> --limit 20`
+2. For each post:
+   a. Check if already commented (use `analyze-post` to see existing comments)
+   b. `analyze-post --post-id <shortcode>` — read thumbnail + caption
+   c. Visually analyze the thumbnail to understand the content
+   d. Write a contextual, natural comment (1~2 sentences, 1~2 emoji max)
+   e. `comment --post-id <shortcode> --text "..."`
+3. Rate limit delays are automatic (5~7min between comments)
+
+### "Follow @user and engage with their feed"
+
+1. `follow --username <user>`
+2. `list-posts --username <user> --limit 20`
+3. Like + comment each post (as above)
+
+### Comment Writing Rules
+
+- Write in the same language as the post caption
+- Be specific to the content — reference what's in the image/caption
+- 1~2 sentences max, 1~2 emoji
+- No hashtags in comments
+- No generic phrases like "Nice post!" or "Great content!"
+- Vary tone and style across comments — don't repeat patterns
+- If the post is a video (릴스), analyze the thumbnail + caption to understand context
+
+## Rate Limit Safety (New Account)
+
+| Action | Delay | Hourly | Daily |
+|--------|-------|--------|-------|
+| Like | 20~40s | 15 | 500 |
+| Comment | 5~7min | 5 | 100 |
+| Follow | 1~2min | 15 | 250 |
+| Unfollow | 1~2min | 10 | 200 |
+| DM | 2~5min | 5 | 30 |
+| Post | 1~2min | 3 | 25 |
+
+All delays are randomized and applied automatically. Counters persist across sessions per userId.
+
+## Error Recovery
+
+| Error | Action |
+|---|---|
+| `hourly_limit` | Wait for the specified time, then retry |
+| `daily_limit` | Wait until tomorrow |
+| `rate_limit` (spam detected) | Wait 24~48 hours |
+| `challenge` (302 redirect to /challenge/) | User must verify identity in browser |
+| `SESSION_EXPIRED` | Run `login` again |
+
+## Important Notes
+
+- Always check `rate-limit-status` before bulk operations
+- New accounts (< 20 days) have stricter limits
+- Uniform action intervals trigger bot detection — delays are randomized
+- challenge requires manual browser verification
+- Session + counters stored locally at `~/.viruagent-cli/sessions/insta-session.json`