Macaly Cloud

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

Get the app's LIVE preview URL to share with the user. Call it when the user wants to see the app — typically once after your last write_file's preview rebuild succeeds (get_project reports previewBuildStatus). It never triggers a build; it creates a temporary, exact-app access link valid for three hours.

preview_app

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 until status is READY (or ERROR, then check get_logs with log_type 'deploy').

publish_app

Read one project file by path. Pass `path` exactly as list_files returned it. A missing path is a NOT_FOUND error. Responses are capped at 100000 characters (truncated: true marks a partial read).

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

Import a file (image, video, document, …) into the app's media-asset storage from a publicly reachable http/https URL, and get back its permanent public URL — usable directly in the app's code or fetchable into the sandbox via bash. Max 1 GB. The file must already be reachable at a URL: this tool cannot accept file bytes (never paste file contents or base64 into a tool argument). If the user's file exists only on their computer, use list_media instead — it returns a link to the app's media library for them to drop the file into. Do not upload their 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 (no partial edits), producing one git commit and one history entry per call. 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"; 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 — import a URL with upload_file, 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