analyze_pdf
ChatGPTRead a PDF or other document that is already at a public URL, for example one the app will reference, and answer a prompt about it: summary, text, tables, requirements. The URL must be reachable without login. For a file the user attached in this conversation, read it yourself instead. urlContextMetadata reports whether the URL could be retrieved. A large document can take a few minutes. Uses the workspace's Macaly credits, based on size.
analyze_youtube_video
ChatGPTWatch a YouTube video and answer a prompt about it (summary, notes, steps, UI or design details) as source material for the selected Macaly app. Accepts youtube.com/watch, youtu.be and youtube.com/shorts URLs. Send the whole video without offsets by default; one call handles long videos. Pass startOffset and endOffset only to analyze one specific segment (processed frame by frame, so keep it under 20 minutes), or after a timeout. Takes up to about 90 seconds. Uses the workspace's Macaly credits, based on length.
check_domain_availability
ChatGPTCheck whether a domain name can be registered through Macaly and what it costs. Pass a root domain such as example.com (no www or other subdomain). Returns isAvailable, canBeRegistered (available and within Macaly's price limit), isTooExpensive, isOwnedByUser (the user already registered it through Macaly), price (USD) and period (years). It only checks: registering a domain is not available through this connector; the user does it in Macaly's Domains settings. To attach a domain the user already owns, use connect_domain.
connect_domain
ChatGPTConnect a custom domain to a published app. Returns the DNS records to configure at your registrar; the domain goes live once DNS verifies. Requires a plan that allows custom domains.
create_app
ChatGPTCreate a new, EMPTY Macaly app that YOU will write the code for. Macaly provides the infrastructure (git repo, sandbox, build, hosting) — its own coding agent is NOT started, no AI build runs, and the conversation starts with no messages. Projects use the platform's default template: TanStack Start (React 19) + Vite + Tailwind, with Convex as the backend (provisioned via the setup-convex-db skill when needed). The response includes a briefing (stack, non-negotiable boundaries, conventions, workflow) — read it before writing any code. Returns a chatId immediately; the workspace bootstraps in the background and you can start writing right away (a first write on a cold workspace just takes ~20-30s longer). With kind "scratchpad" it instead returns your hidden scratchpad for utility work (skills, one-off scripts, file processing): one per team, reused across calls, never listed in list_projects or the dashboard, and never publishable.
create_test_google_grant
ChatGPTSign a reserved test identity in through the selected app's "Sign in with Google" (added with the google-auth guide) in the sandbox browser, where Google's real consent screen cannot run. Open the app first with run_project_command (agent-browser open) in the browser session you test with. In one call, Macaly stores the sign-in handoff in that page, mints a one-time grant for an e2e+<id>@e2e.macaly.dev identity, which can never match a real Google account, and opens the app's own /auth/google/callback, which signs in through the app's code; then wait for the app's signed-in state. It never contacts Google, and returns no grant or secret. Signing in creates a test user, or with linkToSignedInUser links one, in the database the app currently uses. Counts one Cloud action.
delete_file
ChatGPTDelete one file and commit the deletion immediately (one git commit and one history entry per call). Same claiming and protected-path rules as write_file.
deploy_database
ChatGPTDeploy the app's Convex backend (convex/schema.ts and the Convex functions) from the current project files. On this connector it replaces running .sandbox/deploy-convex-app: call it after every change under convex/. It first checks the code on an isolated local Convex backend, then compares its public function contract with Live. target must be the database the app currently uses (get_project.database.sandbox.environment: Testing is testing, Live is live); this tool never switches it and refuses a mismatch. Testing: the change deploys even when it is not yet compatible with Live, and the result lists what to fix before publishing. Live: an incompatible or unverifiable change is not deployed, and a deploy immediately changes the backend the published app uses. Read message, and on failure the last lines of deployment.output; follow nextStep.
duplicate_app
ChatGPTDuplicate an app (with its history) into a fresh one you can edit independently — the same as 'Duplicate' in the Macaly dashboard. Returns the new app's chatId. This provisions a workspace, so it can take a while.
edit_file
ChatGPTChange part of one existing text file and commit it immediately: each edit replaces oldText with newText, in order, against the file's current content (uncommitted command changes included). oldText must match the file exactly, including spaces and line breaks, and must match one place unless replaceAll is true. All edits apply together or none does: a missing or ambiguous match (EDIT_NO_MATCH / EDIT_AMBIGUOUS_MATCH) changes nothing. Produces one git commit and one history entry, and the same claiming, protected-path, size and preview rules as write_file. Up to 20 edits per call. After your last change, typecheck with run_project_command ".sandbox/check-errors --strict".
edit_image
ChatGPTChange an existing image for the selected Macaly app with AI: restyle or retouch it, or add, remove or replace elements, optionally guided by reference images. The result is saved to the app's media library as a new image; the input images are not changed. Pass inputImageUrl, or inputImageUrls with the image to change first and references after it. Input images are public URLs, e.g. from list_media, upload_file or generate_image; never a preview_app access link. To make a background transparent, use remove_image_background instead. Returns imageUrl, a public, permanent link to use in the app's code. You cannot see the image, so never claim it matches the request; share imageUrl with the user. Can take up to about two minutes. Each call uses the workspace's Macaly credits.
fetch_webpage
ChatGPTFetch one public webpage as markdown (text, headings, links and full image URLs) to reference or recreate it in the selected Macaly app. For normal marketing, docs and content pages; it cannot log in, crawl several pages or extract structured records. For images of a page, use screenshot_webpage. Returns up to the first 40,000 characters; a longer page is marked truncated with totalChars and nextOffset, and calling again with the same url and offset set to nextOffset reads the next part from a copy Macaly keeps for 15 minutes, at no charge. Never pass a preview_app access link. Each new fetch uses the workspace's Macaly credits.
generate_image
ChatGPTCreate a new image from a text prompt for the selected Macaly app (hero, mockup, illustration, icon, favicon); the result is saved to the app's media library. Only for the app: for an image the user just wants to look at, use your own image generation. To change an existing image, use edit_image; to make a background transparent, use remove_image_background. Returns imageUrl, a public, permanent link to use in the app's code. You cannot see the image, so never claim it matches the request; share imageUrl with the user. Can take up to about two minutes. Each call uses the workspace's Macaly credits. For image generation inside the finished app, write a Convex action as the ai-image guide shows.
generate_music
ChatGPTGenerate an AI music track for the selected Macaly app (background music, a jingle, a song); it is saved to the app's media library. Only for the app. Takes the music-generation guide's prompt, lyrics, style and instrumental; there is no mode, outputFormat or providerOptions: lyrics and style apply whenever given, and the track is MP3. Returns a jobId at once; the track takes about 1 to 3 minutes: call get_media_job with that jobId (each call waits up to waitSeconds), never wait with run_project_command, and never start the same track again while it runs. Its 40,000 credits are reserved when the job starts and charged when the provider finishes generating; a generation that fails or times out is not charged, but if saving the finished file then fails, the credits stay charged (the provider was paid). A repeat call with the same fields while the job runs returns the same job and is not charged again. You cannot listen to it: share audioUrl with the user. For music generation inside the finished app, write a Convex action as the music-generation guide shows.
generate_speech
ChatGPTTurn text into speech for the selected Macaly app (voice-over, greeting, narration, pronunciation clips); each clip is saved to the app's media library. Only for the app's audio. Same options as the text-to-voice guide, with its providerOptions as top-level fields: style and languageCode for gemini, pitch and volume for minimax, emotion for both. Pass text for one clip, or items (up to 10) for several in one call; the other top-level fields apply to every item that does not set its own. Returns audioUrl, a public, permanent link to use in the app's code; with items, a result or an error for each item. You cannot listen to the audio, so never claim it sounds right; share audioUrl with the user. Each clip uses the workspace's Macaly credits. For speech inside the finished app, write a Convex action as the text-to-voice guide shows.
generate_video
ChatGPTGenerate a 5- or 10-second AI video for the selected Macaly app, e.g. a hero background; it is saved to the app's media library. Only for the app. Same parameters as the video-generation guide, without providerOptions (generateAudio and cfgScale are fields). Returns a jobId at once; the video takes about 2 to 5 minutes: call get_media_job with that jobId (each call waits up to waitSeconds), never wait with run_project_command, and never start the same video again while it runs. Provider "seedance2" needs the user's agreement to its cost: its first call starts nothing and returns costConfirmationRequired with the exact credits and a costConfirmationId; tell the user the cost, and only after they agree in the conversation call again with chatId and costConfirmationId. Credits from the guide's pricing table (160,000 to 600,000) are reserved when the job starts, so the workspace balance shows them as used, and charged when the provider finishes generating; a generation that fails, is refused or times out is not charged, but if saving the finished file then fails, the credits stay charged (the provider was paid). A repeat call with the same fields while the job runs returns the same job and is not charged again. startImageUrl is a public image URL, e.g. from generate_image or list_media, never a preview_app access link. You cannot watch the video: share videoUrl with the user. For video generation inside the finished app, write a Convex action as the video-generation guide shows.
get_database_usage
ChatGPTRead how the app's Convex database is being used, to find hot, slow or failing functions and to explain backend cost. Returns two independent parts: history, 7 days of stored daily usage (function calls, documents and bytes read, file egress; Live and Testing combined) plus this month's workspace overage; and functions, a recent snapshot of the busiest functions over the last 15 or 60 minutes (calls, p50/p99 latency, errors, cache hit rate). Either part can be unavailable; then continue with a code review instead of retrying in a loop. The snapshot refreshes at most every 90 seconds, is not billing data, and must never be described as 24-hour or 7-day data.
get_deployment
ChatGPTGet the newest publish attempt of the app, or the one named by deploymentId: status (QUEUED/BUILDING/READY/ERROR), deployment url and connected domains. liveUrl is the URL of the version that is live now; give the user liveUrl, not url. During a re-publish, liveUrl keeps the previous version until the new one is READY. Poll after publish_app with its id until READY or ERROR. On ERROR, call get_logs with log_type 'deploy' and the same deploymentId for the build stderr.
get_icon
ChatGPTGet the SVG markup of one Streamline item, by the hash from search_icons, to embed in the selected Macaly app's code as inline SVG. Same download options as the icon-search guide: size (default 48), responsive (default true), colors (literal HEX codes or CSS color names), backgroundColor, strokeWidth and strokeToFill. Returns svg, the markup, up to 24,000 characters; a larger item is refused. SVG only: for a raster image, embed the SVG instead. The markup is for the app's code only: never upload it to the media library or serve it as a standalone file, and keep its <desc> credit. Uses no Macaly credits.
get_live_site_logs
ChatGPTDiagnose the published (live) site. It requests one path on the live URL and returns the HTTP status plus the server runtime log lines recorded for that path during a short listening window, with a note on how to read them. Call it first when the user says the live site is broken, returns 500, or behaves differently from the preview, before guessing a cause or republishing. Quote a matching log line verbatim; credentials in it come back as <redacted>. It never runs browser JavaScript, so a 2xx with no logs does not prove the page renders. Requires a published app. At most 6 calls per 10 minutes per app, shared with Macaly's own agent; each call takes up to about 45 seconds. For build errors of a publish, use get_logs 'deploy'.
get_logs
ChatGPTFetch real logs for the project, head/tail-truncated. log_type: 'build' = latest preview build (status, failure reason, build output errors); 'dev_server' = tail of the live sandbox dev-server log (boots the sandbox if needed, ~20s cold); 'deploy' = the newest publish attempt, or the one named by deploymentId, and its build stderr from the hosting provider.
get_media_job
ChatGPTRead a video or music job that generate_video or generate_music started, by its jobId; without jobId, list this app's 10 newest jobs (each with a prompt excerpt, provider and duration) without waiting. While a job is queued or running, the call waits up to waitSeconds for it to finish, then returns nextPollAfterSeconds; never wait with run_project_command. Keep calling it in this turn while it runs; if it is still running after about 3 calls, tell the user it is generating and that you can check when they ask, and never start the same generation again because a read is pending. A finished job returns videoUrl or audioUrl, a public, permanent link already in the app's media library, and creditsCharged; a failed one returns error, charged and what to do next. Reading costs nothing.
get_messages
ChatGPTRead the app's conversation history. The first page holds the newest messages and nextCursor pages backward to older ones; within a page, messages are in chronological order (oldest first). Use it to catch up on the chat before making changes — what the user asked for and what was built so far. Returns each message's role, plain text and creation time plus a tool-call count; internal build traces and tool payloads are omitted to keep responses small.
get_preview_status
ChatGPTRead 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_project
ChatGPTProject status snapshot: preview build state, preview URL, newest publish status, liveUrl (the URL to give the user for the version that is live now), and active claims. Pass includeBriefing: true to also get the project briefing (stack, boundaries, conventions, workflow and working rules) — create_app already returned it, so leave it off when polling, but pass it once when you continue an existing app in a new conversation. Decide your next action: agentTurnPhase='idle' → write_file/edit_file/delete_file to make changes (each call commits immediately; no need to wait for anything after create_app). agentTurnPhase != 'idle' → Macaly's own agent is working on this app; do NOT write, retry later. activeEditor set → another external editor wrote recently (sameUser: true means another app connected to the same Macaly account, which shares this worktree). After your last write → typecheck with run_project_command ".sandbox/check-errors --strict"; on problems → get_logs. previewUrl serves content once previewBuildStatus='succeeded' (builds run automatically after bootstrap and shortly after your last write). Use publish_app only when the user asks to go live; then poll get_deployment.
get_seo_audit
ChatGPTRead an SEO audit of the app. Pass the auditId request_seo_audit returned: a publish creates a newer published-site audit, and without auditId you get the newest report of any kind. state is not_requested, building (capturing the files and deploying the temporary preview), auditing, completed, or failed with error. While it is building or auditing, the call waits up to waitSeconds for the state to change, then returns nextPollAfterSeconds; never wait with run_project_command. Make no file writes until it leaves building. If it is still building or auditing after a few calls, tell the user it is running and check back later with get_seo_audit (no auditId needed); never start another run because a read is pending. A completed audit returns score, category scores, findings (failed and warning checks with their affected pages), auditedPaths and page patterns; includeFullReport adds page summaries and performance metrics. Compare auditedPaths with the app's routes before claiming full-site coverage.
get_site_analytics
ChatGPTRead visitor analytics for the app's published site. report 'overview' returns visitors, pageviews, visits, bounceRate and visitDuration, each as total plus diff: the relative change vs the previous period of equal length (1 = +100%, -0.5 = -50%). The other reports rank pages, referrers, countries, browsers, device types or UTM values (pass utmParameter for 'utm'). Start with 'overview', then drill down. Defaults: the last 7 days for 'overview' and 30 days for the rest; the oldest custom domain connected to the app, else its oldest Macaly address, else its generated Macaly address. The result's legend gives the units: tell the user '+50%', not 'diff 0.5', and bounce rate as a percentage. An app that is not published now returns published: false unless you pass domain, which reads an earlier address's past visits; zero or empty results mean the site has had no visitors in that period.
get_test_otp
ChatGPTGet the one-time code the selected Macaly app just emailed to a reserved test address, to finish an email-code sign-in, email verification or password reset while testing the app in the sandbox browser. Only e2e+<id>@e2e.macaly.dev addresses work: Macaly keeps their codes instead of emailing them, for apps that send codes through Macaly (the auth-otp and email-and-password-auth guides). Submit the address in the app and wait until the code field is visible, then call this tool and type the code with run_project_command (agent-browser fill) in the same browser session. Each code is returned once and then deleted, and expires 5 minutes after it was sent. Status 'pending' means no code is waiting after waitSeconds: not sent yet, already returned, or expired; have the app send a new one. Never use a real person's email or a fixed code.
import_database_data
ChatGPTImport data into the app's Convex database: a Convex snapshot ZIP, or a CSV, JSON array or JSONL file for one table. On this connector it replaces the deploy-convex-app guide's npx convex import. If convex/schema.ts changed since the last deploy, deploy it with deploy_database first. target must be the database the app currently uses (get_project.database.sandbox.environment: Testing is testing, Live is live); this tool never switches it and refuses a mismatch. A Live import changes the published app's data at once: get the user's explicit go-ahead in the conversation, then pass liveAuthorized true. Choose mode from the user's request: requireEmpty imports only into empty tables; append adds rows; replace replaces the imported tables (with a ZIP, every table in it, including sign-in tables when the export has them); replaceAll, ZIP only, also clears every table the ZIP lacks, including sign-in data, so use it only when the user asked to replace the whole database. Macaly backs up Live before a Live replace or replaceAll. Pass the file as path, a file in the app's sandbox (prefer /tmp/, which is never committed), or as mediaAssetId only for a file the user already put in the media library: upload_file publishes a file at a public URL, so never upload a data file just to import it. Export spreadsheets as CSV first. CSV cells import only as numbers or strings: for booleans, ids, arrays, objects or empty cells, convert the file to JSONL first. table is required for CSV and JSON files and not allowed for a ZIP. A long import returns status in_progress with importId: call again with only chatId and importId to read its state. An identical import within 15 minutes is not run again; to run it once more when the user asks for the same rows again, pass the repeatToken its result returned. Publish never copies Testing data to Live. Read message and follow nextStep.
list_connectable_domains
ChatGPTList exact hostnames already owned at this project’s hosting provider, including whether each can be connected. This does not search registrar availability or purchase domains.
list_files
ChatGPTList the project's source file paths (paginated array of strings). Use read_file to fetch a file's contents.
list_media
ChatGPTList the files in the app's media library — everything uploaded by the user or added with upload_file — so you can reference their public URLs from the app's code. Check here before asking the user for an image; they may already have uploaded it. The response also includes an uploadUrl: a link to this app's media library. When the user has a file only on their computer and you cannot send it yourself with upload_file (no local shell, or the upload host is blocked), send them that link, ask them to drag the file in, and call this tool again to pick it up. No tool can accept raw bytes.
list_projects
ChatGPTList 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_teams
ChatGPTList 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_variants
ChatGPTList the app's variants: alternative versions with their own code and chat, sharing the app's data, uploads and live URL. Returns each variant's id, name, branch, saved headCommitHash and macalyUrl, plus activeId (the active variant, the one this connector's tools edit), revision and lastPublishedId (the variant the live site serves; null if never published). Inspect saved code with git through run_project_command (git show '<commit>:<path>', git diff '<a>' '<b>'); saved commits leave out uncommitted edits. Creating, switching, renaming and deleting variants happen in Macaly, not here: share macalyUrl, or a variant's macalyUrl to open that variant there; switching changes which variant this connector edits. Not available for scratchpads.
mention_projects
ChatGPTSearch 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.
open_preview_panel
ChatGPTOpen 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.
preview_app
ChatGPTGet 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.
publish_app
ChatGPTPublish 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.
read_file
ChatGPTRead 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.
remove_image_background
ChatGPTMake the background of one image transparent for the selected Macaly app, e.g. a logo, product photo or portrait for a colored section. The result is saved to the app's media library as a new image; the input image is not changed. The default provider redraws the image with AI, which can change details and size; for an exact cut-out of a logo, photo or product, pass provider "nanobanana". Input images are public URLs, e.g. from list_media, upload_file or generate_image; never a preview_app access link. Returns imageUrl, a public, permanent link to use in the app's code. You cannot see the image, so never claim it matches the request; share imageUrl with the user. Each call uses the workspace's Macaly credits.
rename_app
ChatGPTRename a Macaly app. This changes the title shown in the user's project list and dashboard. Use it when the user asks for a new name, or when the auto-generated title no longer matches what the project has become. Use a short, concrete product name (2-6 words) and leave a title that is still accurate alone. This does not change the app's URL; use rename_subdomain for that.
rename_subdomain
ChatGPTChange the app's free Macaly address, e.g. to better-name.macaly.app. Pass only the label ('better-name'); the app must already be published, and the old Macaly URL stops working immediately. Visitor analytics start fresh under the new address. If another app holds that address, nothing changes and the response returns moveConfirmationRequired: explain that the address will be removed from that app at once, and retry with moveFromChatId only after the user explicitly agrees. For a domain the user owns, use connect_domain instead.
repair_platform_env
ChatGPTRestore the platform-managed connection variables in the app's Convex deployment with a freshly issued token: MACALY_API_TOKEN, MACALY_BASE_URL, MACALY_CHAT_ID, MACALY_DATABASE_ENVIRONMENT and MACALY_APP_FILES_PROTOCOL (plus a preview bypass header where one is needed). Use it when a Convex function gets 401 or 403 from Macaly platform APIs, including '403 Missing required scope', or when those variables are missing or wrong; set_env_vars cannot set them. It repairs the deployment the app currently targets (Live or Testing), revokes the token it replaces, and checks the other deployment in the background. Requires an existing database. Never ask the user for these values.
request_seo_audit
ChatGPTRequest an SEO audit of the app's current code, including uncommitted edits. Macaly captures the sandbox's files, deploys them to a temporary noindex preview, audits it, saves the findings and removes the preview; it never publishes the app or touches its domain, so never publish just to get a report. Finish your file edits first. Returns an auditId with state 'building'. Make no file writes until get_seo_audit says it left building: edits before that, by you or Macaly's agent, fail the audit, and you can request it again. Then read the report with get_seo_audit and this auditId. One audit runs per app at a time, and a run still pending after 20 minutes is reported as failed. Not available for scratchpads.
run_project_command
ChatGPTUse 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.
screenshot_webpage
ChatGPTCapture a screenshot of the selected Macaly app or of a public webpage, as images to share with the user or to keep as a design reference. You cannot see the images, so never claim from them that a page looks right. target "preview" captures the app's preview as the user sees it (pass path for a subpage); it needs a successful preview build (get_project.previewBuildStatus). "sandbox" captures the live dev server in the app's sandbox, with the latest files before the preview rebuilds, and may start the sandbox. "external" captures a public url. Without target, a url means external and no url means preview. Same parameters as the webpage-screenshot guide. Returns imageUrls: public, permanent image links, also for the private preview; a tall page comes in several parts, top to bottom. Never pass a preview_app access link as url. Each screenshot uses the workspace's Macaly credits.
search_icons
ChatGPTSearch Streamline icons, illustrations, emojis and design elements for the selected Macaly app, e.g. to replace emoji or default icons on a landing page. Same parameters as the icon-search guide: query, productType (default "icons"), offset, limit (default 20), productTier and style. Returns results with hash, name, imagePreviewUrl, isFree, family and category, and pagination with nextOffset. You cannot see imagePreviewUrl: choose by name and family, or share the previews with the user; never reference them from the app. Pass a result's hash to get_icon for its SVG markup. Uses no Macaly credits.
search_platform_docs
ChatGPTSearch the documentation for the selected app's workspace to answer how-to questions about the platform: publishing, domains, database, settings. Returns results with title, link and content. Describe only what the results support, and give the user the returned link exactly; never build documentation URLs yourself. For platform API access, tell the user to contact support.
search_stock_photos
ChatGPTSearch Pexels stock photos for the selected Macaly app (hero, backgrounds, section imagery). Only for building the app; for photos the user just wants to see, use your own search. Same parameters as the stock-photo-search guide: query, orientation, size, color (a color name or a hex code such as "#FF0000"), page and per_page (default 4, at most 80). Returns photos with the Pexels page url, photographer credit, average color, src links (medium, large, large2x) and alt text, and next to pass back as given for more. You cannot see the photos: choose by alt and share the links with the user. Credit photographers as "Photo by NAME on Pexels". Uses no Macaly credits.
search_web
ChatGPTResearch what building or debugging the selected Macaly app needs: library and API documentation, install steps, reference content. Only for that work; answer general questions with your own browsing instead. Returns an answer with citations, search_results (title, url, snippet, date) and images. Set deepResearch for detailed library or API documentation with exact install steps; it is slower (often 20 to 60 seconds) and costs more. Each search uses the workspace's Macaly credits. For search inside the finished app, write a Convex action that calls the endpoint as the internet-search guide shows; this tool is for your own research.
set_env_vars
ChatGPTSave API keys, URLs and other settings that the app or its Convex functions read from process.env. Values are merged into the project's .env.local (other variables are kept), committed, and synced to every attached Live and Testing Convex deployment, so Convex functions see them right away; app code reads its values after the next preview build or publish. It cannot delete a variable; an empty string is stored as a value. Platform-managed names (MACALY_, CONVEX_, SITE_URL, auth keys and similar) are refused and listed in blockedVars; use repair_platform_env for MACALY_* problems. Never give a secret a VITE_ or NEXT_PUBLIC_ name, because those reach the browser.
setup_api_domain
ChatGPTGive the app's Convex HTTP actions (MCP servers, webhooks, public APIs) a stable https://<deployment>.api.macaly.app address served through Macaly, instead of the default *.convex.site URL. New databases usually get it automatically; call this to add it to an older app or to check its status. It is idempotent, so calling it again is also how you poll. Returns the domain and a status: 'verified' (live) or 'pending' (a legacy domain still verifying; report it as the address and keep working). Needs a Live database. In code, read MACALY_CONVEX_SITE_URL ?? CONVEX_SITE_URL instead of hardcoding the address.
setup_database
ChatGPTCreate the app's Convex database (its backend) and connect the project to it, or refresh the connection credentials of an existing one. On this connector it replaces running the setup-convex-db provision script: do not run that script. It writes and commits the connection values to .env.local, the backend helper convex/macaly.ts and, for TanStack apps, the @/convex/* import alias, and returns only variable names, never their values. Call it once before writing any Convex code; calling it again on an app that has a database refreshes its credentials. It refuses, before creating anything, if convex/macaly.ts or tsconfig.json holds a custom setup it must not overwrite. Follow nextStep in the result.
setup_payments_sandbox
ChatGPTSet up or restore the app's payments keys (test, or live if the user switched to live in Macaly). Read skill_info "payments" first: it lists the questions to ask, and call this only after the user has said what they sell and how they want to be paid. Macaly creates the app's payments sandbox, or reuses the existing one, merges the publishable key, secret key, webhook secret and mode into .env.local, commits it, and syncs the secret, webhook secret and mode to the app's Convex deployments. It works before or after setup_database, and returns variable names only, never values. Calling it again is safe and restores missing keys. Afterwards follow skill_info "stripe-checkout" (Embedded Checkout only) and install stripe, @stripe/stripe-js and @stripe/react-stripe-js. Follow nextStep: it says whether the app is in test or LIVE mode. If status is 'expired', write no payment code: send the user to macalyUrl's Payments tab, and call again once they say they set up a new sandbox. Never overwrite .env.local wholesale, never mention Stripe to the user and never share Stripe links.
skill_info
ChatGPTRead 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.
transcribe_audio
ChatGPTTranscribe the speech in an audio file to text for the selected Macaly app (captions, notes, content to build from). Pass exactly one of audioUrl, a public URL (e.g. from list_media), or path, a file in the app's sandbox, which Macaly reads on the server without storing it anywhere. At most 25 MB; mp3, mp4, mpeg, mpga, m4a, wav, webm, ogg, flac. Never pass base64 audio or a preview_app access link. Returns text; a transcript longer than 40,000 characters is marked truncated with totalChars, nextOffset and transcriptId, and calling again with that transcriptId and offset set to nextOffset reads the next part from a copy Macaly keeps for 15 minutes, at no charge. Each new transcription uses the workspace's Macaly credits, based on the audio's length. For transcription inside the finished app, write a Convex action as the voice-to-text guide shows.
upload_file
ChatGPTPut 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.
write_file
ChatGPTWrite 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.
connect_domain
Claudecreate_app
Claudedelete_file
Claudeduplicate_app
Claudeget_deployment
Claudeget_logs
Claudeget_project
Claudelist_files
Claudelist_projects
Claudelist_teams
Claudepreview_app
Claudepublish_app
Clauderead_file
Clauderun_project_command
Claudeskill_info
Claudewrite_file
Claude
