CLI reference¶

Slash commands work in the REPL and as a one-shot (insto [@user] -c <cmd> [args]). The single grammar is intentional — the REPL is just a prompt around the same dispatcher. Top-level setup, watch-daemon, and watch-service have their own lifecycle and are not slash commands.

Global flags¶

Every command inherits these via the global parser. Flag conflicts (e.g. --json and --csv) raise a CommandUsageError with a clear message.

Flag	Effect
`--json [DEST]`	Write versioned JSON envelope (`{"_schema": "insto.v1", "command": ..., "target": ..., "captured_at": ..., "data": ...}`). `DEST = -` writes to stdout, `DEST` omitted writes to `output/<user>/<cmd>.json`.
`--csv [DEST]`	Same, flat-row commands only. CSV has no `_schema` envelope (just header + rows).
`--maltego [DEST]`	Maltego entity-import CSV (`Type, Value, Weight, Notes, Properties`). Limited to commands with a canonical entity per row.
`--output-format {json,csv,maltego}`	Long form of the three above.
`--limit N`	Override per-command default. `N=0` means no cap (only honored where the command itself disables the cap).
`--no-download`	Media commands print URLs and skip CDN streaming.
`--yes`	Skip interactive confirmations (`/batch` over 25 targets, `/purge`).
`--proxy URL`	Per-call proxy. Schemes: `http://`, `https://`, `socks5h://` (Tor).
`--hiker-token TOKEN`	Per-call HikerAPI token override.
`--backend {hikerapi,aiograpi}`	Per-invocation backend selector (overrides `$INSTO_BACKEND` and `config.toml`).
`--no-progress`	Suppress tqdm bars + `⢿ <cmd>...` spinner on long-running commands.
`--non-interactive`	`insto setup` only — read every value from env vars without prompts. CI/automation.
`--verbose` / `--debug`	Bump log level (writes to `~/.insto/logs/insto.log`, rotated).

Top-level subcommands¶

insto                                  # REPL (default)
insto @instagram                       # REPL with @instagram pre-selected as the target
insto -c info instagram                # one-shot; inline target
insto setup                            # interactive config wizard
insto watch-daemon                     # foreground executor for persisted watches
insto watch-service install            # macOS user LaunchAgent, no sudo
insto watch-service status --json       # credential-free status, no provider calls
insto watch-service uninstall          # preserves monitoring data and credentials
insto --print-completion {bash|zsh}    # emit completion script (needs insto[completion])
insto --version
insto --help

watch-service is macOS-only and takes no global credential flags. Its complete surface is install [--env-file /absolute/path/file.toml], status [--json], and uninstall. Status JSON uses schema_version: 1, not the slash-command export envelope; it distinguishes installation, registration, optional process diagnostics, database availability, and persisted watches. See macOS user service for secrets and recovery.

Slash-command groups¶

Target¶

Command	Purpose
`/target <user>`	Set the active session target (pre-resolves pk for fail-fast).
`/current`	Print the active target.
`/clear`	Drop the active target.

Launching insto @user pre-selects the target for the REPL session and shows it in the welcome banner + prompt (insto @user>). Startup validates the name locally (no network — so a cold backend never stalls spin-up); the pk resolves on first use. /target keeps its interactive pre-resolve.

Profile¶

Inline target: /info instagram. Active target used otherwise.

Command	Purpose
`/info`	Full profile + `user_about` payload (folded into the panel). Avatar URL is rendered as a clickable link; `created` and `country` come from the about call.
`/about`	Raw `user_about` slice on its own (joined date, country, former usernames). One backend call instead of two.
`/propic`	Download HD profile picture.
`/pinned`	Pinned posts (Instagram caps at 3).
`/email` / `/phone`	Public contact fields if present.
`/export`	Profile + about as JSON (always JSON, ignores `--csv`).

Media¶

Command	Purpose
`/stories`	Active stories (24h TTL).
`/highlights [--download N]`	List highlights; `--download N` fetches items of the Nth one.
`/posts [N]`	Last N feed posts (default 12).
`/reels [N]`	Last N reels — pulled from feed and filtered (default 10).
`/tagged [N]`	Posts where the target is tagged (default 10).
`/reposts [N]`	Posts the target reposted via IG's repost surface (hikerapi only).
`/audio <track_id> [N]`	Clips that use a given audio asset id.
`/postinfo <ref>`	Resolve a media URL / shortcode / pk → full `Post` DTO. No active target needed.

Network¶

Command	Purpose
`/followers [N]`	First N followers (default 50).
`/followings [N]`	First N accounts the target follows (default 50).
`/mutuals`	Followers ∩ following of one target. Default 1000 per side; `--limit 0` for no cap.
`/intersect <a> <b>`	Followers(@a) ∩ followers(@b) — cross-target shared audience.
`/similar`	IG's "Suggested for you" list (`chaining` API).
`/recommended`	IG's category-based recommendations (business / creator accounts). aiograpi only.
`/search <query> [N]`	Free-text account search (no active target needed).

Content analysis¶

All content commands operate on a bounded window (default 50 posts; override with --limit). The output header always names the window so a result of 3 hashtags is not mistaken for the user's only 3 hashtags ever.

Command	Purpose
`/hashtags`	Top hashtags in captions.
`/mentions`	Top @-mentions (caption + usertags).
`/captions`	Dump captions of recent posts.
`/likes`	Aggregate like-count stats.
`/timeline`	Posting cadence histogram — hour-of-day sparkline + day-of-week bars.

Geo¶

Command	Purpose
`/locations`	Top geo-tagged location names from the active target's posts.
`/where`	🔥 Geo fingerprint of the active target — anchor (most-frequent place), centroid, max radius, top places bar chart.
`/place <query> [N]`	Search Instagram places by free text → name + GPS + IG location pk.
`/placeposts <pk> [N]`	Top posts at a given Instagram location pk.

Interactions¶

All take a bounded post window (default 50). /wliked and /fans make N (or 2N) backend calls — pass --limit 10 for cheaper sampling. Concurrency capped at 5 internally.

Command	Purpose
`/comments [post_code]`	Comments for one post code, or aggregate across the window.
`/wcommented`	Top users commenting on the target's recent posts.
`/wliked`	Top users liking the target's recent posts.
`/wtagged`	Top users who tagged the target in their posts.
`/fans`	🔥 Composite ranking: `score = likes + 3×comments`. Output shows ❤️ + 💬 breakdown.

Discovery¶

Command	Purpose
`/resolve <url>`	Expand `instagram.com/share/...` short-link → canonical URL. aiograpi only.

Direct¶

Command	Purpose
`/direct [--participant QUERY] [N]`	List recent Direct threads for the logged-in aiograpi account (default 20); optional filter matches participant username, display name, or thread title.
`/direct-thread <thread_id> [N]`	Show recent messages in one Direct thread (default 20).

Direct commands are aiograpi-only, read-only, and support JSON export. They intentionally expose no send, reaction, seen, unsend, mute, approve, upload, or title-update flows.

Saved¶

Command	Purpose
`/collections [N]`	List saved collections for the logged-in aiograpi account (default 20).
`/saved [--collection ID_OR_NAME] [N]`	List saved posts, optionally scoped to a saved collection id or exact collection name (default 20).

Saved commands are aiograpi-only, read-only, and support JSON/CSV export. They intentionally expose no save, unsave, collection-create, edit, delete, or other account-mutation flows.

Batch¶

/batch <file> <subcommand> [subcommand-args]
/batch - info                  # read targets from stdin (one per line)

Concurrency cap 3 (override --concurrency N, hard ceiling 10).
1s ± 25% jitter between target starts.
Resume across re-runs via output/.batch-<sha>.jsonl. --restart clears.
Confirms above 25 targets unless --yes.
Graceful exit on QuotaExhausted (saves resume state).

Watch / diff / history¶

Command	Purpose
`/watch <user> [interval]`	Persist or explicitly reactivate a watch (≥ 5 min interval, max 3 active). With no user, uses the active target.
`/unwatch <user>`	Delete a persisted watch and stop its local task.
`/watching`	List persisted watches with state, last success, redacted error, and consecutive-error count.
`/diff <user>`	Diff current profile vs the most recent stored snapshot.
`/history [N]`	Last N rows of `cli_history`.

One-shot registration exits after writing the row; it never becomes an executor:

insto @nasa -c watch 600
insto watch-daemon

The REPL and daemon use the same sqlite registry and a per-database POSIX lock, so exactly one process executes watches while every process can add, remove, or list them. The owner reconciles external changes within about two seconds. Daemon startup reports recovered watches and estimated load. Ctrl+C and SIGTERM drain in-flight tasks before resources and the lock are released.

Each failed tick gets one immediate retry. Two consecutive failed ticks persist paused; AuthInvalid and Banned pause immediately. Re-run /watch to reactivate with a fresh registration identity. The minimum-interval maximum is 36 ticks/hour, estimated at 72-108 backend calls/hour across three targets. HikerAPI polling consumes quota and may incur cost; aiograpi polling increases rate-limit and logged-in-account risk.

Operational¶

Command	Purpose
`/quota`	Fresh `/sys/balance` snapshot — requests left, USD balance, rate cap.
`/health`	Backend ping + last error + schema-drift counter.
`/config`	Effective config + per-key source (flag / env / toml / default).
`/purge {history,snapshots,cache} [--user @u]`	Wipe one of the local stores. Always confirms unless `--yes`.
`/theme`	Open the interactive picker — `↑`/`↓` live-preview each theme on the banner, `Enter` applies, `Esc`/`q` cancels.
`/theme <name>`	Switch directly to a theme. Applies live (banner + prompt repaint, no restart) and persists in `~/.insto/config.toml`.
`/help`	List every registered command, grouped by category.
`/exit`, `/quit`	Leave the REPL (also Ctrl+D).

Themes (/theme <name>): aiograpi (default), amber (80s amber CRT), claude (burnt orange), cyberpunk (neon), hacker (matrix phosphor green), instagram (brand gradient).

REPL shortcuts¶

Key	Action
`Ctrl+L`	Clear screen + redraw the welcome banner
`Ctrl+T`	Print the active target
`Ctrl+C`	Cancel the current input line (stay in the REPL)
`Ctrl+D`	Exit on an empty line

These are also listed in the welcome banner's "Shortcuts" block.

`/dossier`¶

/dossier
/dossier --no-download         # everything except media
insto -c dossier instagram --limit 50

Collects a full target package under output/<user>/dossier/<ts>/:

output/instagram/dossier/2026-04-27T14:35Z/
├── MANIFEST.md                # human-readable summary (with partial=true if quota ran out)
├── profile.json
├── posts.json
├── followers.csv
├── following.csv
├── mutuals.csv
├── hashtags.csv
├── mentions.csv
├── locations.csv
├── wcommented.csv
├── wtagged.csv
└── posts/                     # media files (skipped with --no-download)

Pre-flight gates:

Profile must be public. private / blocked / deleted aborts before any other request — no directory created.
Disk free must be ≥ 2 GB. Otherwise abort.

Independent sections fan out via asyncio.gather(return_exceptions=True) — if one section errors (RateLimited, QuotaExhausted), the rest still complete and MANIFEST.md flags partial: true with the failure list.