agent-instagram

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Instagram

An Instagram DM CLI for AI agents. Supports browser cookie extraction (zero-config, extracts from Chromium browsers) and username/password authentication (with 2FA). Uses Instagram's private mobile API to read and send direct messages.

Use one of these entrypoints:

Global install:
```
agent-instagram ...
```

One-off execution:

bunx --package agent-messenger agent-instagram ...

一款面向AI Agent的Instagram私信CLI工具。支持浏览器Cookie提取（零配置，从Chromium内核浏览器提取）和用户名/密码认证（支持双因素认证2FA）。利用Instagram的私有移动API来读取和发送私信。

使用以下任一方式启动：

全局安装：
```
agent-instagram ...
```

一次性执行：

bunx --package agent-messenger agent-instagram ...

Key Concepts

核心概念

Thread ID = Instagram's identifier for a DM conversation. Numeric string returned by
```
chat list
```
.
Browser cookie extraction = recommended auth method. Extracts cookies from Chromium browsers (Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium) where you're logged into instagram.com. Zero-config.
Username/password auth = fallback method. Authenticates using Instagram credentials. Supports two-factor authentication via SMS or authenticator app.
HTTP-based = each command makes HTTP requests and returns. No persistent connection or background process.
Multi-account = multiple Instagram accounts can be stored. Use
```
auth list
```
and
```
auth use
```
to switch between them.
DM-only = this CLI focuses on Instagram Direct Messages. It does not manage posts, stories, or followers.

Thread ID = Instagram对私信对话的标识符。通过
```
chat list
```
命令返回的数字字符串。
浏览器Cookie提取 = 推荐的认证方式。从已登录instagram.com的Chromium内核浏览器（Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium）中提取Cookie。零配置。
用户名/密码认证 = 备选方式。使用Instagram凭证进行认证。支持通过短信或认证器应用实现双因素认证。
基于HTTP = 每个命令都会发起HTTP请求并返回结果。无持久连接或后台进程。
多账户支持 = 可存储多个Instagram账户。使用
```
auth list
```
和
```
auth use
```
命令切换账户。
仅支持私信 = 此CLI专注于Instagram私信功能。不管理帖子、故事或粉丝。

Quick Start

快速开始

bash

undefined

bash

undefined

Extract cookies from browser (recommended — zero-config)

从浏览器提取Cookie（推荐——零配置）

agent-instagram auth extract

Or: Log in with Instagram credentials (fallback)

或者：使用Instagram凭证登录（备选）

agent-instagram auth login --username myaccount --password "mypassword"

List DM conversations

列出私信对话

agent-instagram chat list

Send a message

发送消息

agent-instagram message send <thread-id> "Hello from agent-instagram"

undefined

agent-instagram message send <thread-id> "Hello from agent-instagram"

undefined

Authentication Flow

认证流程

Instagram supports two authentication methods:

Browser cookie extraction (recommended): Extracts your session cookies from a Chromium browser where you're logged into instagram.com. Zero-config, no password needed.
Username/password login: Authenticates using Instagram credentials with optional two-factor verification.

Sessions are persisted locally so you don't need to re-authenticate for every command. Browser extraction auto-runs when no session exists.

Instagram支持两种认证方式：

浏览器Cookie提取（推荐）：从已登录instagram.com的Chromium内核浏览器中提取会话Cookie。零配置，无需密码。
用户名/密码登录：使用Instagram凭证进行认证，可选双因素验证。

会话会本地持久化存储，因此无需每次执行命令都重新认证。当不存在有效会话时，浏览器提取会自动运行。

Browser Cookie Extraction (Recommended)

浏览器Cookie提取（推荐）

agent-instagram auth extract

reads your Instagram session cookies from Chrome, Edge, Arc, Brave, Vivaldi, or Chromium. You must be logged into instagram.com in one of these browsers.

bash

undefined

agent-instagram auth extract

会从Chrome、Edge、Arc、Brave、Vivaldi或Chromium浏览器中读取你的Instagram会话Cookie。你必须在其中一款浏览器中登录过instagram.com。

bash

undefined

Extract cookies from browser — zero-config

从浏览器提取Cookie——零配置

agent-instagram auth extract

With debug output

开启调试输出

agent-instagram auth extract --debug

Scan custom Chromium profile/user-data dirs

扫描自定义Chromium配置文件/用户数据目录

agent-instagram auth extract --browser-profile ~/browser-data agent-instagram auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"


`--browser-profile` accepts repeatable or comma-separated Chromium profile/user-data directories. Use it for agent-browser profiles, custom Chrome user data dirs, or portable browser profiles.

**How it works**: The CLI reads Instagram cookies (`sessionid`, `csrftoken`, `ds_user_id`) directly from the browser's SQLite cookie database. No browser automation, no password prompts. The session is stored locally in `~/.config/agent-messenger/`.

**When to re-extract**: Browser cookies expire. When your session expires, re-run `agent-instagram auth extract` or let auto-extraction handle it (the CLI attempts extraction automatically when no valid session exists).

**Supported browsers**: Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium

agent-instagram auth extract --browser-profile ~/browser-data agent-instagram auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"


`--browser-profile` 接受重复输入或逗号分隔的Chromium配置文件/用户数据目录。可用于Agent浏览器配置文件、自定义Chrome用户数据目录或便携浏览器配置文件。

**工作原理**：CLI直接从浏览器的SQLite Cookie数据库中读取Instagram Cookie（`sessionid`、`csrftoken`、`ds_user_id`）。无需浏览器自动化，无需密码提示。会话会本地存储在`~/.config/agent-messenger/`目录下。

**何时重新提取**：浏览器Cookie会过期。当会话过期时，重新运行`agent-instagram auth extract`命令，或让自动提取功能处理（当不存在有效会话时，CLI会自动尝试提取）。

**支持的浏览器**：Chrome、Chrome Canary、Edge、Arc、Brave、Vivaldi、Chromium

Agent Behavior (MANDATORY)

Agent行为（强制要求）

When a command fails because no account is configured, the agent MUST drive the auth flow itself. Never tell the user to run commands. The agent runs everything.

Step 1: Check for existing accounts

bash

agent-instagram auth list

If accounts exist, use

agent-instagram auth use <account-id>

and retry the original command.

Step 2: Try browser extraction first

bash

agent-instagram auth extract

当命令因未配置账户而失败时，Agent必须自行驱动认证流程。绝不能让用户手动运行命令。Agent会自动执行所有步骤。

步骤1：检查现有账户

bash

agent-instagram auth list

如果存在账户，使用

agent-instagram auth use <account-id>

命令切换，然后重试原命令。

步骤2：优先尝试浏览器提取

bash

agent-instagram auth extract

-> {"authenticated":true,"account_id":"12345678","username":"myaccount"}


If extraction succeeds, proceed with the original command.

**Step 3: If extraction fails, ask for credentials**

Ask the user for their Instagram username and password. These are the ONLY things the user needs to provide.

**Step 4: Start login**

```bash
agent-instagram auth login --username myaccount --password "mypassword"


如果提取成功，继续执行原命令。

**步骤3：如果提取失败，请求凭证**

向用户索要其Instagram用户名和密码。这是用户唯一需要提供的信息。

**步骤4：开始登录**

```bash
agent-instagram auth login --username myaccount --password "mypassword"

-> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}


**Step 4: Handle 2FA if required**

If login returns `two_factor_required`, ask the user for the verification code:

```bash


**步骤4：处理必要的双因素认证**

如果登录返回`two_factor_required`，向用户索要验证码：

```bash

-> {"two_factor_required":true,"two_factor_identifier":"abc123","message":"..."}


Then complete verification:

```bash
agent-instagram auth verify --username myaccount --code 123456 --identifier abc123


然后完成验证：

```bash
agent-instagram auth verify --username myaccount --code 123456 --identifier abc123

-> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}


**Step 5: Retry the original command**

After successful auth, immediately execute whatever the user originally asked for.


**步骤5：重试原命令**

成功认证后，立即执行用户最初请求的操作。

Common Auth Commands

常用认证命令

bash

agent-instagram auth extract                 # Extract cookies from browser (recommended)
agent-instagram auth extract --debug         # Extract with debug output
agent-instagram auth status                  # Check current auth state
agent-instagram auth status --account <id>   # Check specific account
agent-instagram auth list                    # List all stored accounts
agent-instagram auth use <id>                # Switch active account
agent-instagram auth logout                  # Remove current account
agent-instagram auth logout --account <id>   # Remove specific account

bash

agent-instagram auth extract                 # 从浏览器提取Cookie（推荐）
agent-instagram auth extract --debug         # 开启调试输出提取Cookie
agent-instagram auth status                  # 检查当前认证状态
agent-instagram auth status --account <id>   # 检查特定账户的认证状态
agent-instagram auth list                    # 列出所有已存储的账户
agent-instagram auth use <id>                # 切换活跃账户
agent-instagram auth logout                  # 移除当前账户
agent-instagram auth logout --account <id>   # 移除特定账户

Memory

内存管理

The agent maintains a

~/.config/agent-messenger/MEMORY.md

file as persistent memory across sessions. This is agent-managed. The CLI does not read or write this file. Use the

Read

and

Write

tools to manage your memory file.

Agent会维护一个

~/.config/agent-messenger/MEMORY.md

文件，作为跨会话的持久化内存。此文件由Agent管理。CLI不会读取或写入此文件。使用

Read

和

Write

工具管理内存文件。

Reading Memory

读取内存

At the start of every task, read

~/.config/agent-messenger/MEMORY.md

using the

Read

tool to load any previously discovered thread IDs, contact names, and preferences.

If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
If the file can't be read (permissions, missing directory), proceed without memory.

在每个任务开始时，使用

Read

工具读取

~/.config/agent-messenger/MEMORY.md

文件，加载之前发现的Thread ID、联系人名称和偏好设置。

如果文件尚未存在，无需担心。继续执行任务，当首次有有用信息需要存储时再创建该文件。
如果无法读取文件（权限问题、目录缺失），无需内存即可继续执行。

Writing Memory

写入内存

After discovering useful information, update

~/.config/agent-messenger/MEMORY.md

using the

Write

tool. Write triggers include:

After discovering thread IDs and contact names (from
```
chat list
```
)
After discovering group conversation names and participants
After the user gives you an alias or preference ("call this the family group", "my work chat is X")

When writing, include the complete file content. The

Write

tool overwrites the entire file.

发现有用信息后，使用

Write

工具更新

~/.config/agent-messenger/MEMORY.md

文件。触发写入的场景包括：

发现Thread ID和联系人名称后（来自
```
chat list
```
命令）
发现群组对话名称和参与者后
用户提供别名或偏好设置后（例如“将这个称为家庭群组”、“我的工作聊天是X”）

写入时，需包含完整的文件内容。

Write

工具会覆盖整个文件。

What to Store

存储内容

Thread IDs with contact/group names
Your own username and user ID
User-given aliases ("family group", "work chat")
Commonly referenced thread IDs
Any user preference expressed during interaction

带有联系人/群组名称的Thread ID
你自己的用户名和用户ID
用户指定的别名（例如“家庭群组”、“工作聊天”）
经常引用的Thread ID
交互过程中用户表达的任何偏好设置

What NOT to Store

禁止存储内容

Never store auth credentials, passwords, session tokens, or any sensitive data. Never store full message content (just IDs and chat context).

绝不要存储认证凭证、密码、会话令牌或任何敏感数据。绝不要存储完整的消息内容（仅存储ID和聊天上下文）。

Format / Example

格式 / 示例

markdown

undefined

markdown

undefined

Agent Messenger Memory

Instagram Account

Username: myaccount
User ID: 12345678

Username: myaccount
User ID: 12345678

Conversations

```
340282366841710300949128138443434234567
```
- Alice (private)
```
340282366841710300949128138443434234568
```
- Bob (private)
```
340282366841710300949128138443434234569
```
- Project Team (group, 5 members)

```
340282366841710300949128138443434234567
```
- Alice (private)
```
340282366841710300949128138443434234568
```
- Bob (private)
```
340282366841710300949128138443434234569
```
- Project Team (group, 5 members)

Aliases

"alice" ->
```
340282366841710300949128138443434234567
```
"project" ->
```
340282366841710300949128138443434234569
```
(Project Team)

"alice" ->
```
340282366841710300949128138443434234567
```
"project" ->
```
340282366841710300949128138443434234569
```
(Project Team)

Notes

User prefers --pretty output


> Memory lets you skip repeated `chat list` calls. When you already know a thread ID from a previous session, use it directly.

User prefers --pretty output


> 内存功能可让你跳过重复的`chat list`调用。当你从之前的会话中已知道某个Thread ID时，可直接使用它。

Commands

命令列表

Auth Commands

认证命令

bash

undefined

bash

undefined

Extract cookies from browser (recommended — zero-config)

从浏览器提取Cookie（推荐——零配置）

agent-instagram auth extract agent-instagram auth extract --debug

Log in (interactive: prompts for username/password)

登录（交互式：提示输入用户名/密码）

agent-instagram auth login

Log in (non-interactive: pass credentials as flags)

登录（非交互式：通过参数传递凭证）

agent-instagram auth login --username <username> --password <password>

Log in with debug output (shows raw API responses)

开启调试输出登录（显示原始API响应）

agent-instagram auth login --username <username> --password <password> --debug

Complete 2FA verification (non-interactive)

完成双因素认证验证（非交互式）

agent-instagram auth verify --username <username> --code <code> --identifier <identifier>

Resolve a security challenge — send verification code

解决安全验证挑战——发送验证码

agent-instagram auth challenge --username <username> --method email agent-instagram auth challenge --username <username> --method sms

Resolve a security challenge — submit verification code

解决安全验证挑战——提交验证码

agent-instagram auth challenge --username <username> --code <code>

Check auth status

检查认证状态

agent-instagram auth status agent-instagram auth status --account <id>

List stored accounts

列出已存储的账户

agent-instagram auth list

Switch active account

切换活跃账户

agent-instagram auth use <id>

Remove account

移除账户

agent-instagram auth logout agent-instagram auth logout --account <id>

undefined

agent-instagram auth logout agent-instagram auth logout --account <id>

undefined

Whoami Command

Whoami命令

bash

undefined

bash

undefined

Show current authenticated user

显示当前已认证用户

agent-instagram whoami agent-instagram whoami --pretty agent-instagram whoami --account <account-id>


Output includes the authenticated user's identity information.

agent-instagram whoami agent-instagram whoami --pretty agent-instagram whoami --account <account-id>


输出内容包含已认证用户的身份信息。

Chat Commands

聊天命令

bash

undefined

bash

undefined

List DM conversations (sorted by most recent activity)

列出私信对话（按最近活动排序）

agent-instagram chat list agent-instagram chat list --limit 50 agent-instagram chat list --account <id>

Search conversations by name

按名称搜索对话

agent-instagram chat search "alice" agent-instagram chat search "alice" --limit 10 agent-instagram chat search "alice" --account <id>


Output includes:
- `id` - thread ID
- `name` - contact or group name
- `type` - `private` or `group`
- `is_group` - boolean
- `participant_count` - number of participants
- `unread_count` - unread message count
- `last_message` - most recent message preview

agent-instagram chat search "alice" agent-instagram chat search "alice" --limit 10 agent-instagram chat search "alice" --account <id>


输出内容包括：
- `id` - Thread ID
- `name` - 联系人或群组名称
- `type` - `private`（私聊）或`group`（群组）
- `is_group` - 布尔值
- `participant_count` - 参与者数量
- `unread_count` - 未读消息数量
- `last_message` - 最新消息预览

Message Commands

消息命令

bash

undefined

bash

undefined

List messages in a conversation

列出对话中的消息

agent-instagram message list <thread-id> agent-instagram message list <thread-id> --limit 50 agent-instagram message list <thread-id> --limit 10 --account <id>

Send a text message to a thread

向指定对话发送文本消息

agent-instagram message send <thread-id> <text> agent-instagram message send <thread-id> "Hello!" --account <id>

Send a text message to a user by @username

通过@用户名向用户发送文本消息

agent-instagram message send-to <username> <text> agent-instagram message send-to @alice "Hello!"

Search messages by text content

按文本内容搜索消息

agent-instagram message search <query> agent-instagram message search "meeting" --thread <thread-id> agent-instagram message search "hello" --limit 10

Search Instagram users by username

按用户名搜索Instagram用户

agent-instagram message search-users <query> agent-instagram message search-users "alice"

undefined

agent-instagram message search-users <query> agent-instagram message search-users "alice"

undefined

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:

json

{
  "id": "340282366841710300949128138443434234567",
  "name": "Alice",
  "type": "private",
  "is_group": false,
  "participant_count": 2,
  "unread_count": 3,
  "last_message": {
    "id": "29876543210987654",
    "thread_id": "340282366841710300949128138443434234567",
    "from": "12345678",
    "timestamp": "2026-03-29T10:30:00.000Z",
    "is_outgoing": false,
    "type": "text",
    "text": "See you tomorrow!"
  }
}

所有命令默认输出JSON格式，供AI使用：

json

{
  "id": "340282366841710300949128138443434234567",
  "name": "Alice",
  "type": "private",
  "is_group": false,
  "participant_count": 2,
  "unread_count": 3,
  "last_message": {
    "id": "29876543210987654",
    "thread_id": "340282366841710300949128138443434234567",
    "from": "12345678",
    "timestamp": "2026-03-29T10:30:00.000Z",
    "is_outgoing": false,
    "type": "text",
    "text": "See you tomorrow!"
  }
}

Pretty (Human-Readable)

美观格式（人类可读）

Use

--pretty

flag for formatted output:

bash

agent-instagram chat list --pretty

使用

--pretty

参数获取格式化输出：

bash

agent-instagram chat list --pretty

Global Options

全局选项

Option	Description
`--pretty`	Human-readable output instead of JSON
`--account <id>`	Use a specific account for this command

选项	说明
`--pretty`	输出人类可读格式，而非JSON
`--account <id>`	为此命令使用特定账户

Common Patterns

常见使用模式

Check unread messages

查看未读消息

bash

undefined

bash

undefined

List conversations to see unread counts

列出对话查看未读数量

agent-instagram chat list --limit 20

Read messages from a specific conversation

读取特定对话中的消息

agent-instagram message list <thread-id> --limit 10

undefined

agent-instagram message list <thread-id> --limit 10

undefined

Send a message to a contact

向联系人发送消息

bash

undefined

bash

undefined

Find the contact first

先找到联系人

agent-instagram chat search "Alice"

Send to the thread ID

向对应的Thread ID发送消息

agent-instagram message send <thread-id> "Hey, are we still on for tomorrow?"

undefined

agent-instagram message send <thread-id> "Hey, are we still on for tomorrow?"

undefined

Reply in a group conversation

在群组对话中回复

bash

undefined

bash

undefined

Find the group

找到群组

agent-instagram chat search "Project Team"

Send to the group thread

向群组对话发送消息

agent-instagram message send <thread-id> "Status update: deployment complete."

undefined

agent-instagram message send <thread-id> "Status update: deployment complete."

undefined

Error Handling

错误处理

All commands return consistent error format:

json

{
  "error": "Not authenticated. Run \"agent-instagram auth login --username <username>\" first."
}

Common errors:

```
Not authenticated
```
- no account configured. Run
```
auth extract
```
or
```
auth login
```
.
```
Session expired or missing
```
- session is no longer valid. Run
```
auth extract
```
to re-extract from browser, or
```
auth login
```
to log in again.
```
Login failed
```
- wrong username/password. Double-check credentials.
```
Two-factor authentication failed
```
- wrong 2FA code. Get a new code and try
```
auth verify
```
again.
```
Rate limited
```
- too many requests. Wait and retry.

所有命令返回一致的错误格式：

json

{
  "error": "Not authenticated. Run \"agent-instagram auth login --username <username>\" first."
}

常见错误：

```
Not authenticated
```
- 未配置账户。运行
```
auth extract
```
或
```
auth login
```
命令。
```
Session expired or missing
```
- 会话已失效或缺失。运行
```
auth extract
```
从浏览器重新提取，或运行
```
auth login
```
重新登录。
```
Login failed
```
- 用户名/密码错误。请仔细检查凭证。
```
Two-factor authentication failed
```
- 双因素验证码错误。获取新验证码后重试
```
auth verify
```
命令。
```
Rate limited
```
- 请求过于频繁。请稍后重试。

Notes

注意事项

Session persistence: Login sessions are stored in
```
~/.config/agent-messenger/instagram/
```
. Sessions may expire if Instagram detects unusual activity.
Ban risk: Instagram monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
Multi-account: Multiple Instagram accounts can be stored simultaneously. Use
```
auth list
```
to see all accounts and
```
auth use <id>
```
to switch.
Text-only: Currently supports text messages only. Media, voice messages, and reactions are read-only (shown as type indicators in message listings).
```
agent-instagram
```
returns JSON by default and
```
--pretty
```
for indented output.

会话持久化：登录会话存储在
```
~/.config/agent-messenger/instagram/
```
目录下。如果Instagram检测到异常活动，会话可能会过期。
封禁风险：Instagram会监控自动化行为。避免高频率发送消息、快速连续发送或批量操作。发送多条消息时请间隔执行命令。
多账户支持：可同时存储多个Instagram账户。使用
```
auth list
```
查看所有账户，使用
```
auth use <id>
```
切换账户。
仅支持文本：目前仅支持文本消息。媒体、语音消息和反应仅可读（在消息列表中显示为类型标识）。
```
agent-instagram
```
默认返回JSON格式，使用
```
--pretty
```
参数可获取缩进格式的输出。

Troubleshooting

故障排除

agent-instagram: command not found

agent-instagram: command not found

agent-instagram
is NOT the npm package name. The npm package is

agent-messenger

If the package is installed globally, use

agent-instagram

directly:

bash

agent-instagram chat list --pretty

If the package is NOT installed, use

--package

to install and run:

bash

npx -y --package agent-messenger agent-instagram chat list --pretty
bunx --package agent-messenger agent-instagram chat list --pretty
pnpm dlx --package agent-messenger agent-instagram chat list --pretty

NEVER run
npx agent-instagram
,
bunx agent-instagram
, or
pnpm dlx agent-instagram
without

--package agent-messenger

. It will fail or install a wrong package since

agent-instagram

is not the npm package name.

agent-instagram
并非npm包名称。npm包名称为

agent-messenger

。

如果已全局安装此包，可直接使用

agent-instagram

：

bash

agent-instagram chat list --pretty

如果未安装此包，使用

--package

参数安装并运行：

bash

npx -y --package agent-messenger agent-instagram chat list --pretty
bunx --package agent-messenger agent-instagram chat list --pretty
pnpm dlx --package agent-messenger agent-instagram chat list --pretty

**绝不要运行

npx agent-instagram

、

bunx agent-instagram

或

pnpm dlx agent-instagram

**而不添加

--package agent-messenger

参数。这会导致失败或安装错误的包，因为

agent-instagram

并非npm包名称。

Login fails with "challenge_required"

登录失败并提示"challenge_required"

Instagram may require additional verification (e.g., confirming your identity from the Instagram app). Open the Instagram app on your phone, complete any security challenges, then try logging in again.

Instagram可能要求额外验证（例如，从Instagram应用确认你的身份）。打开手机上的Instagram应用，完成所有安全验证挑战，然后重试登录。

Session expires frequently

会话频繁过期

Instagram invalidates sessions based on device fingerprinting and activity patterns. If sessions expire often:

Avoid frequent re-authentication
Space out API calls
Don't switch between multiple IP addresses rapidly

Instagram会根据设备指纹和活动模式使会话失效。如果会话经常过期：

避免频繁重新认证
间隔发起API请求
不要快速切换多个IP地址