@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
- 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 withinstafy space init --profile workorinstafy space profile work). - Optional: set defaults with
instafy config set controller-url <url>/instafy config set studio-url <url>
- Link a folder to a space:
- VS Code: install the Instafy extension and run
Instafy: Link Workspace to Space, or - Terminal:
instafy space init
- VS Code: install the Instafy extension and run
- Start the runtime:
instafy runtime start - Check status / stop:
instafy runtime statusinstafy 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
- Optional:
instafy space role <email> <role>— update a teammate's access in the linked space by email.- Works for existing members and pending invites.
buildermeans 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. Usegrepfor 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 readsINSTAFY_CONVERSATION_ID, the conversation a runtime job belongs to.- Add
--transcript --jsonfor original user/assistant text with message IDs and timestamps, without tool events or runtime metadata. JSON messages are newest first;--limitcounts transcript messages (default 80, maximum 200). Each call scans at most 2,000 stored rows. WhenhasMoreis 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--jsonoutput.
- Add
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 intodist/bindat build time;INSTAFY_BIND_BINoverrides it). Seedocs/Bound-Sites.md.instafy agents list— list available top-level agents.instafy agents settings— inspect the linked space's shared multi-agent limits. Add--interactiveto 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 whenINSTAFY_CONVERSATION_IDis 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 optionalmessageto 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
writeScopemetadata 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 sessioninstafy loginsaved; 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--rotateto 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 workspaceno-agentssite 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; ano-reusesite is read and markednoReuse; 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 ano-agentssite (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-loadsand--max-page-loads-per-sitefor 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 (--clearto 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
