npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@instafy/cli

v0.5.10

Published

Run Instafy spaces locally, link folders to Studio, and share previews/webhooks via tunnels.

Readme

Instafy CLI (Preview)

Run Instafy spaces locally and connect them back to Instafy Studio — from any terminal.

Quickstart

  1. Log in once: instafy login
    • Opens a Studio URL; the CLI continues automatically after you sign in.
    • Also enables Git auth (credential helper) for Instafy Git Service. Disable with instafy login --no-git-setup.
    • Multiple accounts: instafy login --profile work (then bind folders with instafy space init --profile work or instafy space profile work).
    • Optional: set defaults with instafy config set controller-url <url> / instafy config set studio-url <url>
  2. Link a folder to a space:
    • VS Code: install the Instafy extension and run Instafy: Link Workspace to Space, or
    • Terminal: instafy space init
  3. Start the runtime: instafy runtime start
  4. Check status / stop:
    • instafy runtime status
    • instafy runtime stop

Common commands

  • instafy runtime start — start a local runtime (agent + origin).
    • A private local start receives a controller-assigned runtime/origin ID, registers without the hosted allocator, and requests its tunnel after registration with no runtime lease.
  • instafy runtime status — show health of the last started runtime.
  • instafy runtime stop — stop the last started runtime.
  • instafy space invite <email> — invite a teammate to the linked space by email.
    • Optional: --role viewer|builder|admin|owner
  • instafy space role <email> <role> — update a teammate's access in the linked space by email.
    • Works for existing members and pending invites.
    • builder means read & write.
    • Fallbacks: --space <id> or --team-id <uuid> when the folder is not linked yet
  • instafy conversation search "<keywords>" — search recent titles/previews and recent messages in at most 12 conversations. Use grep for persisted message content beyond those recent pages.
  • instafy conversation grep "<text>" --json — search authorized persisted user/assistant messages in the linked space, with snippets and exact message IDs.
  • instafy conversation context <conversationId> <messageId> --json — read a bounded window around an exact message, including old messages outside the latest history page.
  • instafy conversation show "<title-or-id>" — inspect one conversation’s messages so you can reuse earlier context in a new chat. With no target it reads INSTAFY_CONVERSATION_ID, the conversation a runtime job belongs to.
    • Add --transcript --json for original user/assistant text with message IDs and timestamps, without tool events or runtime metadata. JSON messages are newest first; --limit counts transcript messages (default 80, maximum 200). Each call scans at most 2,000 stored rows. When hasMore is true, continue with --transcript --cursor <nextCursor>; an empty page can still have older text. This is a text-only view: attachment/card metadata stays available in the unchanged raw --json output.
  • instafy conversation create --parent <conversationId> --thread-kind agent --title "Octo coordination" — create a linked child thread for conversation-native agent coordination.
  • instafy chat --conversation <threadId> "@octo ..." --no-wait — involve another agent by posting a normal message into a normal conversation/thread. Use non-blocking posts from inside an active runtime turn.
    • Like an ordinary Studio chat, the CLI marks the turn as potentially workspace-writing. Controller and member permissions still apply, and read-only questions do not require a file change.
  • instafy bind serve <site> — serve a bound site: a website whose clicks become typed intents, run by a handler script, with records streamed back to every viewer. "Ask Octo" clicks are handed to Studio and sent as the clicker's own chat message, so the binder needs no login. Runs the binder bundled with the CLI (packages/instafy-bind, copied into dist/bind at build time; INSTAFY_BIND_BIN overrides it). See docs/Bound-Sites.md.
  • instafy agents list — list available top-level agents.
  • instafy agents settings — inspect the linked space's shared multi-agent limits. Add --interactive to edit them, or use --max-agents-per-plan <n>, --max-concurrent-agents <n>, and/or --max-native-subagents <n>.
    • Plans default to at most 64 team workers (range 1–256); at most 8 team workers run concurrently across the space (range 1–64), subject to runtime capacity. Lead/root jobs and native helpers are outside the concurrent team-worker count. Native helpers have a separate limit of 3 children per parent (range 1–64), excluding the parent itself; this setting requires a supporting controller. Changing settings requires permission to manage the space; runtime job tokens cannot change them.
  • instafy agents context list --query "<topic>" — inspect optional compact scoped context-card hints for cross-agent coordination.
  • instafy agents context put --agent @octo "<summary>" — save/update a compact context card for the current conversation when INSTAFY_CONVERSATION_ID is set.
  • instafy automations create --name "Octo check-in" --mode space_review --schedule-kind hourly --interval-hours 24 — explicitly opt in to private, quiet space reviews; no custom prompt is needed.
  • instafy recommendations list --limit 200 --json — inspect the linked space's recommendations, including delivery state and accepted or dismissed outcomes visible to this session.
  • instafy recommendations submit --file - --json — read one JSON recommendation from stdin. Add an optional message to deliver a normal private Octo chat with source links; omit it for legacy proposal-only behavior. A workspace file can replace -. Delivery does not start the suggested work. Delivered, accepted and dismissed keys keep their existing outcome.
  • Context cards are a bounded cache, not the primary collaboration path: the controller keeps the newest 200 cards per user/project/agent.
  • Use context cards for soft work focus and overlap hints, not hard locks: note the agent/thread, topic/path/domain, open questions, and where follow-up should go. Structured writeScope metadata remains the safety mechanism for concurrent file edits.
  • instafy mcp — serve your spaces' conversations, your agents' context notes and run diagnostics to a coding agent on this machine over MCP (stdio). The agent starts it, and its calls run as the session instafy login saved; Claude Code gets it with the plugin in claude-plugin/instafy. See docs/CLI.md.
  • instafy git <args...> — run git commands against an Instafy canonical checkout (.instafy/.git) when present.
  • instafy tunnel start — start a detached tunnel for a local port (sticky hostname by default; use --rotate to mint a new one).
    • instafy tunnel list — list local tunnels started by the CLI.
    • instafy tunnel logs <tunnelId> --follow — tail tunnel logs.
    • instafy tunnel stop <tunnelId> — stop + revoke a tunnel.
  • instafy preview check --port <port> — load a local site in a headless browser and list its errors, failed requests and a blank page, with desktop and phone screenshots. Local only; see docs/CLI.md for exit codes and settings.
  • instafy web read <url…> --json — read up to 6 public pages over plain HTTP and get their text, links and structured data with provenance, wrapped as untrusted page content. robots.txt (including AI-agent user agents), optional workspace no-agents site restrictions (the bundled policy has no excluded sites) and translators', caches' and archives' copies of them, private-address checks at every redirect, stop rules and per-turn caps are enforced; a no-reuse site is read and marked noReuse; see docs/CLI.md.
  • instafy web search "<query>" --json — find links to read, in Octo's turns only, with the space's own search key (the web-research skill's providers: Brave, then Kagi). Results are untrusted leads: a link-only site's result keeps only its link and site name, keys go only to their provider's host, nothing is cached, and the room keeps only the query and the count; see docs/CLI.md.
  • instafy web link <site> [name=value…] --json — the link the person opens in their own tab for a no-agents site (guided mode): a configured site's search template from the workspace policy, filled with checked, URL-encoded values, or its home page and what to type there when it bars deep links. Reads nothing.
  • instafy web budget --json — inspect remaining fresh-page reads shared by the current task and its helpers. Cached pages are free.
  • instafy web settings --interactive — space managers configure total and per-site page allowances for new tasks; running tasks retain their original budget. Use --max-page-loads and --max-page-loads-per-site for scripts.
  • instafy secrets list — list space secret metadata (names/descriptions, never values).
  • instafy secrets get <name-or-id> — inspect one space secret metadata entry.
  • instafy secrets put <name> --value ... — create/update a space secret.
  • instafy secrets revoke <name-or-id> — revoke a space secret.
  • instafy credentials list — list your AI provider credentials (short id, kind, provider, model, default marker; never secret material).
  • instafy credentials test <id-or-prefix> — probe one credential through the proxy; exits 1 when it fails.
  • instafy credentials default <id-or-prefix> — pick the credential jobs use by default (--clear to unset).
  • instafy credentials revoke <id-or-prefix> --yes — revoke a credential.
  • instafy support report "Runtime stops after launch" — submit a support report as the signed-in user.
  • instafy support list — list only your own support reports.
  • instafy support show <reportId> — inspect one of your own support reports.
  • instafy support messages <reportId> — read the customer-visible case timeline.
  • instafy support reply <reportId> "More details" — add a follow-up as the reporter.

support report and support reply print their request UUID to stderr before sending. Reuse that value with --client-request-id only when retrying the exact same payload after an uncertain network result; using the same UUID for different content is rejected. Support list/message JSON includes hasMore and a stable nextCursor; pass its paired activity or message cursor flags to read the next page without skipping reports that share a cursor timestamp.

  • instafy diagnostics runtime-events — emit sanitized runtime events for the linked space as versioned JSON.
  • instafy diagnostics run-result <runId> — emit one authorized persisted run result as versioned JSON.
  • instafy providers list — list local providers exposed by the shared provider host surface.
  • instafy providers discover <providerId> — run fresh discovery for one provider.
  • instafy providers read <providerId> <uri> — inspect one provider resource.
  • instafy providers probe <providerId> — run a transport probe against one provider.

Run instafy --help for the public command list and options.

Search conversation context

After instafy login, local agents and terminal users can recover earlier chat evidence without opening Studio:

instafy conversation grep "auth session" --json
instafy conversation grep "auth session" --org <orgId> --limit 20 --json
instafy conversation context <conversationId> <messageId> --before 20 --after 20 --json
rg "auth session" .

Use grep for conversation messages and rg for local files. grep matches literal, case-insensitive text (2–200 characters), not regular expressions. It searches the linked space by default; choose one of --space <id>, --org <id>, --personal, or --all to change scope. Access and conversation visibility are enforced by the controller. These reads do not wake a runtime.

Results are newest first, with a default page of 30 messages (maximum 50). Repeat the same query and scope with --cursor <nextCursor> to continue. JSON includes plain-text snippets, UTF-16 highlight ranges, stable IDs, and pagination. Human output is one escaped line per match: spaceId:conversationId:messageId:role:timestamp: snippet. Exit codes are 0 for matches, 1 for no matches, and 2 for errors, including invalid arguments. JSON no-match output remains a valid empty result page.

context defaults to 20 messages before and after the target (maximum 50 each). JSON retains canonical message IDs in newest-first order and provides olderCursor/newerCursor plus hasOlder/hasNewer. To read farther back, use the older cursor as the next message ID with --before 40 --after 0; to read forward, use the newer cursor with --before 0 --after 40. Adjacent pages repeat their anchor; deduplicate by message ID. Human context is chronological and marks the requested message with >.

Both commands require signed-in user credentials from instafy login, an explicit user --access-token, or INSTAFY_ACCESS_TOKEN/SUPABASE_ACCESS_TOKEN. They do not accept unattended runtime-agent, origin, or service credentials and do not mint runtime tokens. Saved logins remain bound to their controller origin. The controller must support message search/context; older controllers report the unavailable API rather than falling back to a partial recent-message scan.

AI-readable diagnostics

instafy diagnostics is the machine-readable diagnostics surface for local agents such as Codex or Claude Code. Successful commands print the instafy-diagnostics-v1 JSON contract; failures exit non-zero with empty stdout and a human-readable stderr message. They do not require a dashboard and do not scrape process logs.

instafy diagnostics runtime-events --space <spaceId> --limit 50
instafy diagnostics run-result <runId>

These commands accept only signed-in user credentials. The controller applies normal space, conversation, and private-runtime authorization and sanitizes stored runtime-event data. A diagnostic read never creates or enriches a support report automatically; use instafy support report explicitly when information should be sent to support.

For run-result, top-level status: "ready" means a persisted result is available, not that the run succeeded. Inspect the nested result status or outcome before making that decision.

Support and operator boundary

instafy support is the customer-facing support surface. It requires a human user login (or an explicit user access token), and the controller limits list/show operations to reports owned by that user. Reports use the currently linked space by default; pass --no-linked-space to omit that context. Diagnostics are opt-in: details, metadata, logs, and screenshots are uploaded only when their corresponding flags are supplied, and file inputs must stay within the active workspace. The signed-in account identity, including its email snapshot, is attached for report ownership and support contact; it is not part of the optional diagnostic payload. Use --preview to inspect the upload summary without sending a report. Ordinary users receive a minimized owner-only report view; full triage fields and attachment bytes require operator/service authorization.

Hosted Instafy operator access belongs in a separate, non-public instafy-ops distribution. It is not part of this open-source package. The former ops, raw api, ota, and desktop-updates command groups have been removed from the customer artifact. Saved login tokens are never forwarded or refreshed to a different controller origin.

Docs

  • CLI reference & troubleshooting: https://github.com/instafy-dev/instafy/blob/main/docs/CLI.md