agent-line

Agent LINE

A TypeScript CLI tool that enables AI agents and humans to interact with LINE through a simple command interface. Features QR code login and email/password authentication for the LINE desktop client protocol.

Key Concepts

Before diving in, a few things about LINE's architecture:

• MIDs = LINE's unique identifiers. Format varies by entity type:
  • u<32hex> for users (e.g., u0123456789abcdef0123456789abcdef)
  • c<32hex> for groups (e.g., c0123456789abcdef0123456789abcdef)
  • r<32hex> for rooms (e.g., r0123456789abcdef0123456789abcdef)
• QR code login = the primary authentication method. The CLI generates a QR code URL, you scan it with your phone, and the session is established.
• Email/password login = an alternative when QR scanning isn't practical.
• Auth token reuse = after initial login, the CLI stores an auth token locally. Subsequent commands reuse it without re-authentication.
• Device types = the CLI registers as ANDROIDSECONDARY by default — a secondary device that coexists with the LINE desktop app. Override with --device:
  • ANDROIDSECONDARY (default) — secondary device, V3-capable, won't kick LINE desktop
  • DESKTOPMAC / DESKTOPWIN — replaces the desktop session (kicks LINE desktop app)
  • IOSIPAD — secondary but limited API (no V3 token refresh)
• Chat ID = an MID that identifies a conversation. Use chat list to discover them.

Quick Start

# QR code login (default, recommended)
agent-line auth login

# List chat rooms
agent-line chat list --pretty

# List messages in a chat
agent-line message list <chat-id>

# Send a message
agent-line message send <chat-id> "Hi"

Authentication

LINE offers three authentication methods:

Method 1: QR Code Login (Recommended)

The default and most common method. No credentials needed.

agent-line auth login

The CLI prints a QR code URL to stderr. The user scans it with the LINE app on their phone. Once scanned, authentication completes automatically.

Flow:

1. CLI requests a QR code session from LINE's server
2. A URL is printed to stderr (e.g., https://line.me/R/au/q/...)
3. User scans the QR code with their LINE mobile app
4. CLI detects the scan and completes login
5. Auth token is stored locally for future use

Method 2: Email/Password Login

For environments where QR scanning isn't possible:

agent-line auth login --email user@example.com --password pass123

Method 3: Token Login

If you already have a valid auth token:

agent-line auth login --token <auth-token>

Device Override

To specify a device type explicitly:

agent-line auth login --device DESKTOPMAC
agent-line auth login --device DESKTOPWIN

Agent Behavior (MANDATORY)

When a command fails because no account is configured, the agent MUST drive the auth flow itself:

Step 1: Check auth status

agent-line auth status

If authenticated, retry the original command.

Step 2: Attempt login

agent-line auth login

Possible responses:

• {"authenticated": true, ...} → Success. Retry original command.
• {"next_action": "scan_qr", "qr_url": "...", "qr_html_path": "/tmp/line-qr-xxx.html", ...} → QR code has been generated. The CLI attempts to open it in the user's browser automatically. If it didn't open, run open <qr_html_path> (macOS) to show the QR code. Tell the user to scan the QR code with the LINE mobile app. The command blocks until the user scans — once scanned, it outputs {"authenticated": true, ...}.
• {"error": "not_connected", ...} → Network issue. Check connectivity and retry.
• {"error": "not_authenticated", ...} → Credentials expired. Re-run auth login.

Important: QR login works in both interactive and non-interactive (agent) sessions. The CLI generates an HTML page with the QR code and opens it in the user's default browser. No TTY is required.

Step 3: Retry the original command

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

IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens. Always use agent-line auth login.

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.

Reading Memory

At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered chat IDs, friend 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. Don't error out.

Writing Memory

After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:

• After login, remember the account_id from the output
• After discovering chat IDs and participant names (from chat list)
• After the user gives you an alias or preference ("call this the work chat", "my group chat with Alice is X")
• After discovering chat structure (group chats, 1:1 chats)

When writing, include the complete file content. The Write tool overwrites the entire file.

What to Store

• Account ID (MID) from login
• Chat IDs with participant names or display names
• User-given aliases ("work chat", "family group")
• Commonly referenced chat IDs
• Any user preference expressed during interaction

What NOT to Store

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

Handling Stale Data

If a memorized chat ID returns an error, remove it from MEMORY.md. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

Format / Example

# Agent Messenger Memory

## LINE Account

- Account ID: `u0123456789abcdef0123456789abcdef`
- Device type: DESKTOPMAC

## Chat Rooms

- `c9876543210abcdef9876543210abcdef` - Work group chat (Alice, Bob, Charlie)
- `u1111111111abcdef1111111111abcdef` - 1:1 with Alice
- `c2222222222abcdef2222222222abcdef` - Family group

## Aliases

- "work" -> `c9876543210abcdef9876543210abcdef` (Work group chat)
- "alice" -> `u1111111111abcdef1111111111abcdef` (1:1 with Alice)

## Notes

- User prefers --pretty output
- Work chat is the most frequently used

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

Commands

Auth Commands

# QR code login (default)
agent-line auth login
agent-line auth login --pretty

# Email/password login
agent-line auth login --email <email> --password <password>
agent-line auth login --email <email> --password <password> --pretty

# Token login
agent-line auth login --token <auth-token>
agent-line auth login --token <auth-token> --pretty

# Device override
agent-line auth login --device DESKTOPMAC
agent-line auth login --device DESKTOPWIN

# Check auth status
agent-line auth status
agent-line auth status --account <account-id>
agent-line auth status --pretty

# List all authenticated accounts
agent-line auth list
agent-line auth list --pretty

# Switch active account
agent-line auth use <account-id>
agent-line auth use <account-id> --pretty

# Logout
agent-line auth logout
agent-line auth logout <account-id>
agent-line auth logout --pretty

Whoami Command

# Show current authenticated user
agent-line whoami
agent-line whoami --pretty

Output includes:

• mid - your LINE MID
• display_name - your display name
• status_message - your status message
• picture_url - your profile picture URL

Friend Commands

# List all LINE friends
agent-line friend list
agent-line friend list --pretty

Output includes:

• mid - friend's MID
• display_name - friend's display name
• status_message - friend's status message
• picture_url - friend's profile picture URL

Chat Commands

# List all chat rooms
agent-line chat list
agent-line chat list --pretty

Output includes:

• chat_id - MID of the chat room
• type - chat type (user, group, room, square)
• display_name - chat name
• member_count - number of members (groups only)

Message Commands

# List messages in a chat room
agent-line message list <chat-id>
agent-line message list <chat-id> -n 50
agent-line message list <chat-id> --pretty

# Send a text message
agent-line message send <chat-id> "Hello world"
agent-line message send <chat-id> "Hello world" --pretty

Message List Output

Each message includes:

• message_id - unique message identifier
• type - message type (text, image, sticker, etc.)
• author_id - sender's MID
• author_name - sender's display name, resolved from contacts (omitted when unresolved)
• text - message text content (E2EE messages are decrypted automatically when key material is available; null when undecryptable)
• decryption_error - present only for E2EE messages that couldn't be decrypted (code: missing_e2ee_key or decrypt_failed)
• sent_at - Unix timestamp (milliseconds)

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

{
  "chat_id": "c0123456789abcdef0123456789abcdef",
  "type": "group",
  "display_name": "Alice, Bob",
  "member_count": 3,
  "unread_count": 5,
  "last_message": {
    "author_id": "u1111111111abcdef1111111111abcdef",
    "text": "Hello everyone!",
    "sent_at": 1705312200000
  }
}

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-line chat list --pretty

Global Options

Option	Description
--pretty	Human-readable output instead of JSON

Common Patterns

See references/common-patterns.md for typical AI agent workflows.

Templates

See templates/ directory for runnable examples:

• post-message.sh - Send messages with error handling
• monitor-chat.sh - Monitor a chat for new messages
• chat-summary.sh - Generate chat summary

Error Handling

All commands return consistent error format:

{
  "error": "not_connected",
  "message": "Not connected to LINE. Run:\n  agent-line auth login"
}

Common errors:

• not_connected - not authenticated. Run agent-line auth login.
• not_authenticated - credentials expired or invalid. Re-run agent-line auth login to get a fresh session.
• qr_timeout - QR code expired before user scanned it. Run auth login again to generate a new QR code.
• invalid_token - the stored auth token is no longer valid. Re-authenticate with auth login.
• login_failed - email/password incorrect or account issue.
• network_error - couldn't reach LINE servers. Check connectivity.
• rate_limited - too many requests. Wait a moment and retry.

Configuration

Credentials stored in ~/.config/agent-messenger/line-credentials.json (0600 permissions).

Config format:

{
  "current_account": "u0123456789abcdef0123456789abcdef",
  "accounts": {
    "u0123456789abcdef0123456789abcdef": {
      "account_id": "u0123456789abcdef0123456789abcdef",
      "auth_token": "...",
      "device_type": "DESKTOPMAC",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  }
}

SDK: Programmatic Usage

LineClient is available as a TypeScript SDK for building scripts and automations.

Setup

import { LineClient } from 'agent-messenger/line'

const client = await new LineClient().login()

Example

try {
  // List chats
  const chats = await client.getChats()

  // Send a message
  if (chats.length === 0) throw new Error('No chats found')
  const chatId = chats[0].chat_id
  const result = await client.sendMessage(chatId, 'Hello from SDK!')

  // Read messages
  const messages = await client.getMessages(chatId, { count: 50 })
} finally {
  client.close()
}

Full API Reference

See the LINE SDK documentation for complete method signatures, types, schemas, and examples.

Limitations

• No auto-extraction of credentials (requires interactive login via QR code or email/password)
• E2EE (Letter Sealing) messages are decrypted automatically when key material is available (restored from a prior QR/email login); without keys, content may be unreadable
• Sending to chats that require E2EE (Letter Sealing) needs E2EE key material from a prior QR/email login; without it such sends fail with e2ee_required
• No file upload support yet
• No sticker or rich message sending (text only)
• No group creation or management
• No group creation or management commands (list only)
• No reactions or emoji responses
• No message editing or deletion
• No voice/video call support
• Chat IDs are MIDs and not human-readable. Use chat list to discover them.

Troubleshooting

agent-line: command not found

agent-line is NOT the npm package name. The npm package is agent-messenger.

If the package is installed globally, use agent-line directly:

agent-line chat list --pretty

If the package is NOT installed, use --package to install and run:

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

Note: If the user prefers a different package runner, use the matching command above.

NEVER run npx agent-line, bunx agent-line, or pnpm dlx agent-line without --package agent-messenger. It will fail or install a wrong package since agent-line is not the npm package name.

QR code expired

QR codes have a short TTL. If the user doesn't scan in time:

1. Run agent-line auth login again to generate a fresh QR code
2. Scan promptly with the LINE mobile app

Token expired

If commands start failing with not_authenticated or invalid_token:

1. Run agent-line auth login to re-authenticate
2. The old token is replaced automatically

E2EE messages unreadable

The CLI decrypts Letter Sealing (E2EE) messages when E2EE key material is available. Keys are provisioned by a QR or email/password login and reused on later sessions. If a message comes back with text: null and a decryption_error of missing_e2ee_key, the session has no usable key — re-run agent-line auth login (QR) to provision E2EE keys.

References

• Authentication Guide
• Common Patterns