CloudShell Tools and Troubleshooting

CloudShell provides five tools that Claude can use to interact with your Insites instance. When you describe what you want to do in plain language, Claude automatically selects the appropriate tool.

insites_deploy

Deploys one or more files to your Insites instance. Large deployments are automatically split into batches for reliability.

Returns: A list of job IDs and the number of batches created. Claude will automatically poll the deployment status until all batches are complete.

Example prompt: Deploy the updated homepage and product page templates to my instance

Supported File Types

The following file extensions are supported for deployment:

.liquid, .graphql, .json, .css, .js, .html, .yml, .yaml, .txt, .svg, .png, .jpg, .jpeg, .gif, .webp, .xml, .csv

Maximum file size: 5 MB per file.

insites_sync_file

Syncs a single file to your Insites instance immediately. Best for quick updates during development when you need to push one file without a full deployment.

Returns: Confirmation that the file was synced successfully.

Example prompt: Sync just the navigation partial to my instance

Tip: For deploying multiple files at once, use insites_deploy instead. It handles batching automatically and is more efficient for multi-file updates.

insites_get_logs

Fetches recent logs from your Insites instance. Use this to debug issues, check for errors, or monitor activity.

Returns: An array of log entries from your instance.

Example prompt: Show me the last 100 logs from my instance - are there any errors?

insites_env_get

Lists all environment variables currently set on your Insites instance.

This tool takes no parameters.

Returns: A list of all environment variable key-value pairs on your instance.

Example prompt: What environment variables are currently set on my instance?

insites_env_add

Adds a new environment variable or updates an existing one on your Insites instance.

Returns: Confirmation that the environment variable was added or updated.

Example prompt: Add a new environment variable called STRIPE_KEY with the value sk_live_abc123

Using CloudShell

Once connected, describe what you want Claude to do in plain language. Claude will automatically use the appropriate tool. Here are more examples of what you can ask:

• Deploy files: Deploy the updated homepage and product page templates to my instance
• Check logs: Show me recent logs from my instance - are there any errors?
• Manage environment variables: Add a new environment variable called API_KEY with this value: abc123
• Sync a single file: Sync just the navigation partial to my instance
• Review instance state: What environment variables are currently set on my instance?

Troubleshooting

Tools Not Appearing After Restart

Make sure Claude Desktop was fully quit and not just the window closed. If tools still do not appear, the config file likely has a JSON syntax error - a missing comma or bracket will prevent it from loading. Paste the contents of your config file into a JSON validator to find and fix any formatting issues, then restart Claude Desktop.

npx: command not found

Node.js is not installed, or npx is located in a different path than the one in your config. Open a terminal and run the following to find the correct path:

which npx

Copy the path it returns and use it as the command value in your config file, then restart Claude Desktop.

macOS note: If you installed Node.js via nvm (a version manager) rather than from nodejs.org or Homebrew, the path will look different - for example, /Users/yourname/.nvm/versions/node/v18.x.x/bin/npx. Always use the output of which npx as the command value.

Authentication Error or 401 Unauthorized

Your credentials in the config are incorrect. Verify the following:

• The email matches exactly what you use to log in to the Insites Console
• The password is correct
• The instance UUID matches the one on your instance General tab
• There are no spaces before or after the colon in each header value (e.g. x-insites-email:user@example.com not x-insites-email: user@example.com)

Cannot Find Instance UUID

Log in to the Insites Console, select your instance from the list, then click Instance Details and the General tab. The UUID, labelled Instance UUID, has the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Server Unavailable or Connection Error

Check that your internet connection is active. CloudShell runs on AWS and requires an internet connection to operate. If the problem persists, contact your Insites account manager.

Deploy Failures

If a deployment fails, check the following:

• The file extension must be in the supported list (see insites_deploy above)
• Each file must be under 5 MB
• The file path must be valid for an Insites instance (e.g. starting with app/)
• Use insites_get_logs to check your instance logs for more details on the failure