CloudShell Tools

CloudShell gives your AI assistant a set of tools for working with your Insites instance. You never call these yourself: describe what you want in plain language and your AI picks the right tool. This page lists every tool so you know what is possible, with an example prompt for each.

This page lists the 27 tools in CloudShell 1.2.2.

How Tools Choose an Instance

Every tool that works on an instance takes an optional instance UUID. When your AI passes one, the tool acts on that instance for that request only, and the selection does not change. When it passes none, the tool uses the instance selected for the session with insites_select_instance. Every result names the instance the tool acted on. insites_list_instances works on your account, so it takes no instance UUID, and insites_select_instance takes the UUID of the instance to select. See Working on Several Instances.

Signing In

There is no sign-in tool. You sign in when you add CloudShell to your AI assistant: your browser opens and you sign in with your Insites account. After that, CloudShell acts as you, with the access you have in the Console. To sign in again, reconnect CloudShell in your AI assistant, for example with /mcp in Claude Code.

Instances

Tool	What it does	Example prompt
insites_list_instances	Lists every instance in the Insites accounts you belong to, and shows which one is selected.	Which Insites instances can I work on?
insites_select_instance	Selects the instance that every other tool works on in this AI session. Each session keeps its own selection, so selecting here does not move another session. To act on a different instance for one request, your AI names that instance in the request instead.	Select my staging instance.

Deploying

Tool	What it does	Example prompt
insites_deploy	Deploys one or more small files, with their contents sent directly. Best for files under about 32 KB.	Deploy the updated homepage and header partial.
insites_sync_file	Deploys a single small file immediately. Useful for quick edits during development.	Sync just the navigation partial.
insites_request_upload	Creates a one-time upload link for a large file, so the file goes straight from your computer to CloudShell instead of through the AI. Takes HTML, Liquid, CSS, JavaScript, GraphQL, YAML and JSON files, images, fonts, PDFs, and audio and video. Any other type is refused before the upload.	Deploy the 200 KB stylesheet in my assets folder.
insites_commit_upload	Deploys a text file that was sent through an upload link, including GraphQL, YAML and JSON files. Will not replace a file CloudShell knows is there unless asked, and keeps the replaced file for 30 days. If that copy cannot be kept, the replace is refused with the reason, and you can ask for it to go ahead without a copy.	(Used automatically after an upload.)
insites_upload_asset	Deploys an image, font, PDF, audio or video file through an upload link and returns its public URL. Supports PNG, JPG, SVG, WebP, GIF, ICO, WOFF, WOFF2, TTF, OTF and PDF, and audio and video up to 100 MB: MP3, M4A, WAV, OGG, MP4, WebM and MOV. Audio and video are saved in app/assets/media.	Upload logo.png and use it in the header. Upload intro.mp4 and play it on the homepage.
insites_deploy_from_url	Deploys a file from a public https address. Built for web-based AI assistants that cannot read your files.	Deploy the file at https://example.com/home.liquid as my homepage.
insites_deploy_status	Reports the progress of a deploy started from an upload or a link.	Has that deploy finished?
insites_delete_file	Deletes one file from your instance. Your AI only uses it when you ask for a file to be deleted. CloudShell keeps a copy of the file for 30 days first, then checks the instance and reports whether the file is confirmed gone. If the copy cannot be kept, the delete is refused with the reason, and you can ask for it to go ahead without a copy. Needs the same role as deploying.	Delete the old pricing page at app/views/pages/pricing-2025.liquid.

Deployment History and Logs

Tool	What it does	Example prompt
insites_deployments	Lists recent deploys from every source (your AI, direct uploads, and GitHub) with status, size, and time.	Show me the last ten deploys.
insites_deploy_stats	Summarizes deploy activity for the current week and the last seven days.	How many times did we deploy this week?
insites_get_logs	Fetches recent logs from your instance.	Check the logs for errors since the last deploy.

Environment and Modules

Tool	What it does	Example prompt
insites_env_get	Lists the environment variables set on your instance.	What environment variables are set?
insites_env_add	Adds an environment variable, or updates one that already exists.	Set MAPS_API_KEY to the key I just gave you.
insites_module_list	Lists the modules installed on your instance.	Which modules are installed?

GitHub

These tools work with the Insites GitHub App. An instance has one GitHub link, and you can also create and manage it from the Repository card on the instance's page in the Console.

Tool	What it does	Example prompt
insites_github_connect	Connects a repository to your instance. If the Insites GitHub App already sees the repository you name, the link is made in one step. Otherwise it returns a link, valid for one hour, where you choose a repository the app already sees or add a new one on GitHub. The instance watches the repository's default branch.	Connect GitHub to my instance. Connect the repository acme/website to this instance.
insites_github_status	Shows the connected repository, the watched branch, and when it was connected.	Which repository is connected?
insites_github_update_branch	Changes the branch your instance watches. Pushes to that branch deploy automatically, and the branch protection moves to the new branch.	Deploy from the staging branch from now on.
insites_github_tree	Lists the files in the connected repository, or in one folder of it.	Show me what is in app/views/pages.
insites_github_pull	Reads one file from the repository.	Open the homepage from the repository.
insites_github_pull_batch	Reads several files from the repository in one request.	Read all the layout files.
insites_github_push	Commits files to the watched branch, which deploys them automatically.	Commit the new contact page.
insites_github_push_branch	Commits files to another branch, creating it if needed. Nothing deploys until it is merged into the watched branch.	Push this work to a branch called feature/contact-form.
insites_github_commits	Lists recent commits with their message, author, and date.	What changed in the last five commits?
insites_github_list_deployments	Lists recent deploys triggered by GitHub pushes.	Did my last push deploy?
insites_github_revert	Adds a commit that puts the repository back as it was before the chosen commit. It lands on the watched branch, so it deploys like any other push.	Revert the last commit and deploy.
insites_github_disconnect	Disconnects the repository. Future pushes stop deploying, and changes on the instance stop being committed.	Disconnect GitHub from this instance.

Troubleshooting

CloudShell tools do not appear

Check that CloudShell is added with the address https://cloudshell.insites.io/mcp and that you have signed in. In Claude Code, run /mcp to see its status and authenticate again if needed. Some assistants only load new tools after a restart.

An instance is missing from the list

CloudShell lists the instances in the Insites accounts you belong to. If one is missing, ask the account owner to add you in the Console.

A tool is refused on an instance

Your role on that instance does not allow it. By default, reading logs and history needs Viewer, setting environment variables and pushing to a branch needs Editor, and deploying needs Developer or above. Ask the account owner to change your role.

A change went to the wrong instance

Every tool works on the instance selected in that AI session, unless your AI names a different instance in the request. Each session keeps its own selection. Ask your AI which instance is selected, select the right one, and deploy again. Every tool result names the instance it acted on.

A large file arrives incomplete

Files over about 32 KB should go through an upload rather than being sent directly. Ask your AI to deploy the file using an upload link.

An upload will not replace a file

An upload does not replace a file that CloudShell knows is on your instance unless you ask. This includes a file that reached the instance another way, such as from GitHub, the Insites CLI or the Instance Admin. Tell your AI that you want to replace the file. CloudShell keeps a copy of the replaced file for 30 days. See Undoing a Change.

A replace or delete is refused because no copy could be kept

Before it replaces or deletes a file, CloudShell saves a 30-day copy of it. If that copy cannot be saved, the change is refused, and the message names the step that failed and the reason. If you do not need the old version back, tell your AI to go ahead without a copy. The version being replaced or deleted is then not recoverable, so keep your own copy, or make sure the file is in GitHub, first.

A deploy fails

Ask your AI to check the deploy status and the instance logs. If the instance refuses a deploy, the deploy is recorded as failed with the reason, so your AI can read the error and fix the file. Check that the file path starts with app/ or modules/.

A file is refused before it deploys

CloudShell refuses a path that contains .. or starts with /, and a file type it does not support, such as AVI video or EOT fonts. The message gives the reason and, where another tool takes that file type, names it. Every image, font and media file is also checked by its contents, so a file whose contents do not match its extension is refused.