Macaly Cloud

List the Macaly apps of a team, most recently updated first (paginated; pinned apps come back in full on the first page only, and later pages return an empty pinnedProjects). Use it to find the chatId of an existing app to inspect or edit — pass it to get_project, list_files, read_file and the write tools.

list_projects

List the project's source file paths (paginated array of strings). Use read_file to fetch a file's contents.

list_files

List the Macaly teams you can act on. Use this to discover the teamId to pass to create_app when connected via OAuth (API keys are scoped to one team and never need it).

list_teams

Open the Macaly live preview panel. Without chatId it lists the apps of a team (teamId, or your first team); with chatId it creates a temporary preview access link for that app. The user opens this panel from the conversation or from the Macaly app in the ChatGPT sidebar; use preview_app to show an app yourself.

open_preview_panel

Search the user's Macaly apps by title for @-mentions in the composer. Returns resource links whose description carries the chatId to pass to other tools. Type "<app>/<file>" (for example "bakery/page") to mention a source file or media item of the matching apps instead; those links also carry the file path or the media's public URL.

mention_projects

Get the app's LIVE preview URL to share with the user. Call it at the end of every turn that changed the app, after the preview rebuild succeeds (get_project reports previewBuildStatus), even when an earlier link is still valid: the call tells Macaly that your turn is finished. Pass path to open a subpage directly (e.g. "/pricing") and give the user that link instead of telling them where to navigate. It never triggers a build; it creates a temporary, exact-app access link valid for three hours.

preview_app

Read the preview build status of a Macaly app, whether the live preview panel may publish it, and its live URL. The live preview panel calls this tool.

get_preview_status

Publish the app to production (make it publicly live at its macaly.app URL). Only call this when the user explicitly asks to go live. Requires at least one committed edit. Asynchronous — poll get_deployment with deploymentId set to the id this tool returns until status is READY (or ERROR, then check get_logs with log_type 'deploy' and the same deploymentId). Then give the user liveUrl from get_deployment.

publish_app

Read one project file by path. Pass `path` exactly as list_files returned it. A missing path is a NOT_FOUND error. Pass startLine and endLine (1-based, inclusive) to read only part of a large file; every response reports totalLines. Responses are capped at 100000 characters: a cut response has truncated: true and nextStartLine, the line to read next.

read_file

Use this when app development requires a project command that file tools cannot perform, such as installing packages, running framework CLIs, migrations, Macaly capability guides, builds, tests, or validation. It runs a full shell from the selected Macaly app's project root inside an isolated cloud sandbox; it cannot access the user's device or other Macaly projects. The command can modify or delete files in the selected project and can contact external internet services. Execution is authorized, time-limited, rate-limited, and audited. Prefer write_file/delete_file for source edits: they create Git history, and protected paths are checked before command-made changes are persisted with the next write_file. Run '.sandbox/check-errors' after the last source change.

run_project_command

Read a Macaly skill's guide (its SKILL.md): what the capability is, plus ready-to-run curl commands for its platform endpoint and the code patterns to apply. Call this BEFORE implementing a platform capability (database, auth, payments, AI, media, search, integrations). Then EXECUTE the guide with the run_project_command tool: its curl commands and scripts run verbatim there (the sandbox has the $MACALY_* credentials they reference); app-runtime patterns the guide shows go into the app with write_file. Example: for a database, skill_info(chatId, "setup-convex-db"), then run the setup script it documents via run_project_command. Available skills: ai-image, analytics, apify-scraping, apify-scraping/google-maps-business, apify-scraping/linkedin-profile, assets-list, assets-upload, auth-otp, beautiful-landing-page, conversation-memory, convex-agent, convex-best-practices, convex-file-upload, convex-performance-audit, create-favicon, database-crud, db-client-loading-pattern, db-security-pattern, db-ssr-seo, debugging-strategy, deploy-convex-app, docx, domain-check, email-and-password-auth, frontend-design, get-conversation, icon-search, integrations, internet-search, llm-usage, macaly-info, music-generation, payments, pdf, pdf-insight, platform-agent-notification, pptx, reapply-convex-env, recreate-from-url, rename-chat, rename-macaly-subdomain, restart-dev-server, security-review, seo-metadata, set-env-vars, setup-convex-db, simple-admin-blog, stock-photo-search, stripe-checkout, stripe-checkout-branding, stripe-checkout-page, stripe-coupons, stripe-setup-sandbox, telegram-bot, test-convex-functions, test-react-nextjs, test-react-tanstack, text-to-voice, transactional-emails, translations, type-error-context, video-generation, view-logs, voice-to-text, web-browser, webpage-fetch, webpage-screenshot, work-with-files, xlsx, youtube-insight.

skill_info

Put a file (image, video, document, …) into the app's media-asset storage and get back its permanent public URL — usable directly in the app's code or fetchable into the sandbox via bash. Max 1 GB. Two sources, pick one: 1. sourceUrl — a publicly reachable http/https URL. The server imports it; the returned url is live immediately. 2. fileSize + contentType (+ localPath) — a file on your own machine or in the project sandbox. The result contains the final url plus a presigned uploadUrl and a ready curlCommand. Run curlCommand where the file is: in your own local shell for a file on your machine, or with this server's command tool for a file in the project sandbox. When it exits 0 the url is live. fileSize and contentType must match the file exactly, or storage rejects the PUT. This needs a shell with network access to the returned uploadHost; if curl cannot connect or fails with HTTP 403 and a proxy note, follow the returned nextStep. Never paste file contents or base64 into a tool argument. Without a local shell and without a public URL, use list_media — it returns a link to the app's media library for the user to drop the file into. Do not upload the user's file to an unrelated third-party host to get a URL.

upload_file

Write one file and commit it immediately: the full content replaces the file at that path, producing one git commit and one history entry per call. To change part of an existing file, use edit_file instead of sending the whole file. Takes a few seconds (acquires the project sandbox). Rejected while Macaly's own agent is working (CHAT_CLAIMED_BY_AGENT). Rejects protected paths (.macaly/, .sandbox/, .git/, node_modules/, package-manager config), path traversal, package.json lifecycle scripts, and removing <MacalyBridge> from src/routes/__root.tsx. Max 256KB per file. After your last write, typecheck with run_project_command ".sandbox/check-errors --strict"; the preview rebuilds automatically. TEXT ONLY — this is source code, not a file transfer. Never write an image, video, font or other binary here, base64-encoded or otherwise: it bloats the repo and the commit, and the app cannot use it. Media belongs in the media library — upload_file takes a public URL or a file from your own disk, or call list_media for a link the user can drop a local file into — then reference the returned public URL from the code.

write_file