Gram

A CLI tool for interacting with Instagram via their undocumented GraphQL/REST API using cookie-based authentication.

Disclaimer

This project uses Instagram's undocumented web API (and cookie auth). Instagram can change endpoints, query IDs, and anti-bot behavior at any time — expect this to break without notice.

Install

npm install -g @arein/gram
# or
pnpm add -g @arein/gram
# or
bun add -g @arein/gram

# one-shot (no install)
bunx @arein/gram whoami

Quickstart

# Show the logged-in account
gram whoami

# View your home feed
gram feed
gram feed --count 50

# View the explore/discover feed
gram explore

# View a post
gram post CxyzABC1234
gram https://www.instagram.com/p/CxyzABC1234/

# View a user profile
gram user instagram
gram user @instagram --json

# Search for users, hashtags, places
gram search "coffee shop"
gram search "photography" --type hashtags

# Like/unlike posts
gram like CxyzABC1234
gram unlike CxyzABC1234

Commands

Feed Commands

• gram feed [-n count] [--json] [--json-full] — get your home feed
• gram explore [-n count] [--json] [--json-full] — get the explore/discover feed

Post Commands

• gram post <shortcode-or-url> [--json] [--json-full] — view a post by shortcode or URL
• gram comments <shortcode> [-n count] [--json] — view comments on a post
• gram likers <shortcode> [--json] — view users who liked a post
• gram <shortcode-or-url> — shorthand for gram post <shortcode-or-url>

User Commands

• gram user <username> [--json] — view a user profile
• gram posts <username> [-n count] [--json] — get a user's posts
• gram following [username] [-n count] [--json] — get users that someone follows (defaults to you)
• gram followers [username] [-n count] [--json] — get someone's followers (defaults to you)

Search

• gram search <query> [--type <type>] [--json] — search for users, hashtags, and places
  • Types: blended (default), users, hashtags, places

Engagement

• gram like <shortcode> — like a post
• gram unlike <shortcode> — unlike a post
• gram save <shortcode> — save/bookmark a post
• gram unsave <shortcode> — unsave/unbookmark a post
• gram comment <shortcode> "<text>" — comment on a post
• gram follow <username> — follow a user
• gram unfollow <username> — unfollow a user

Account

• gram whoami [--json] — show the currently authenticated user
• gram check — check credential availability and sources

Query IDs

• gram query-ids [--refresh] [--json] — inspect or refresh cached GraphQL query IDs

Authentication

Gram uses your existing Instagram web session. It resolves credentials in this order:

1. CLI flags: --session-id, --csrf-token, --ds-user-id
2. Environment variables: SESSION_ID, CSRF_TOKEN, DS_USER_ID (or prefixed with INSTAGRAM_/IG_)
3. Browser cookies via @steipete/sweet-cookie (Safari, Chrome, Firefox)

Required Cookies

• sessionid — Your Instagram session cookie
• csrftoken — Cross-site request forgery token
• ds_user_id — Your user ID (optional but recommended)

Browser Cookie Sources

• Safari: ~/Library/Cookies/Cookies.binarycookies
• Chrome: ~/Library/Application Support/Google/Chrome/<Profile>/Cookies
• Firefox: ~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite

Override browser order via --cookie-source (repeatable).

Config (JSON5)

Config precedence: CLI flags > env vars > project config > global config.

• Global: ~/.config/gram/config.json5
• Project: ./.gramrc.json5

Example ~/.config/gram/config.json5:

{
  // Cookie source order for browser extraction
  cookieSource: ["safari", "chrome", "firefox"],
  chromeProfile: "Profile 1",
  chromeProfileDir: "/path/to/Chrome/Profile",
  firefoxProfile: "default-release",
  cookieTimeoutMs: 30000,
  timeoutMs: 60000
}

Environment shortcuts:

• GRAM_TIMEOUT_MS
• GRAM_COOKIE_TIMEOUT_MS

Global Options

• --session-id <token>: Instagram sessionid cookie
• --csrf-token <token>: Instagram csrftoken cookie
• --ds-user-id <id>: Instagram ds_user_id cookie
• --cookie-source <safari|chrome|firefox>: browser cookie source (repeatable)
• --chrome-profile <name>: Chrome profile name
• --chrome-profile-dir <path>: Chrome/Chromium profile directory
• --firefox-profile <name>: Firefox profile name
• --cookie-timeout <ms>: cookie extraction timeout (milliseconds)
• --timeout <ms>: request timeout (milliseconds)
• --plain: stable output (no emoji, no color)
• --no-emoji: disable emoji output
• --no-color: disable ANSI colors (or set NO_COLOR=1)

Output Formats

• Default: Human-readable terminal output with emoji
• --json: Machine-readable JSON
• --json-full: JSON with raw API response in _raw field
• --plain: Stable output without emoji or colors

Library Usage

Gram can be used as a library:

import { InstagramClient, resolveCredentials } from '@arein/gram';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new InstagramClient({ cookies });

// Get user profile
const userResult = await client.getUser('instagram');
if (userResult.success) {
  console.log(userResult.user);
}

// Get home feed
const feedResult = await client.getHomeFeed();
if (feedResult.success) {
  console.log(feedResult.posts);
}

// Like a post
const post = await client.getPost('CxyzABC1234');
if (post.success) {
  await client.like(post.post.id);
}

// Search
const searchResult = await client.search('coffee', 'users');

Query IDs

Instagram's web app uses query IDs that rotate periodically. Gram:

1. Ships with baseline IDs in src/lib/query-ids.json
2. Caches runtime-discovered IDs at ~/.config/gram/query-ids-cache.json (24h TTL)
3. Can refresh on demand via gram query-ids --refresh

Override cache path: GRAM_QUERY_IDS_CACHE=/path/to/file.json

Development

pnpm install
pnpm run build        # dist/ + bun binary
pnpm run build:dist   # dist/ only
pnpm test
pnpm run lint

License

MIT