Skip to content

Insites AI · Build with AI in your editor

Tutorial: Deploy a Page with Gemini

Last updated 22 November 2026

Connect Gemini CLI to CloudShell and deploy your first page, step by step.

What you will do

This tutorial takes you from nothing to a live page on your Insites site, using Gemini CLI in your terminal. You connect Gemini to CloudShell, choose a site, ask for a page, and check that it is live. It takes about 15 minutes.

For the background, see Use Gemini with Insites and CloudShell MCP.

Before you start

  • An Insites account. The same one you use to sign in to the Console.
  • A site, with the Developer role or above on it. A lower role can read logs but cannot deploy. Use a staging site for your first try.
  • Gemini CLI. Install it and sign in to your Google account by following the Gemini CLI guide.
  • A project folder for your site, open in your terminal.

Step 1: Connect Gemini to CloudShell

In your project folder, run:

gemini mcp add --transport http -s user insites-cloudshell https://cloudshell.insites.io/mcp

This adds CloudShell to Gemini CLI for all your projects. Do not paste a password, API key or site ID anywhere. CloudShell does not need one.

Step 2: Sign in with your Insites account

  1. Start Gemini CLI with gemini. When it asks whether you trust this folder, choose to trust it. Gemini turns off MCP servers in a folder you have not trusted.
  2. Type /mcp auth insites-cloudshell. Your browser opens.
  3. Sign in with your Insites account, the same way you sign in to the Console, and approve the access request.
  4. Back in Gemini CLI, type /mcp list. insites-cloudshell shows as connected.

CloudShell now acts as you, with the same access you have in the Console.

Step 3: Give Gemini the Logic Engine

The Insites Logic Engine is the public set of rules for building on Insites. Paste this as your first message. To keep it for every chat, save it in a file called GEMINI.md in your project folder instead.

Before you write any code for this project, read the Insites Logic Engine at
https://github.com/insites-io/insites-logic-engine
Start with skills/insites/SKILL.md and follow its decision trees, then use the
reference docs in skills/insites/references/ and the rules in logic-engine/rules/.
Whenever you are unsure how something works on Insites, check the Logic Engine
first instead of guessing, and follow its conventions over your own assumptions.

Step 4: Choose your site

Send this, with your own site name:

List my Insites instances, then select the one called my-staging-site.

Gemini asks you to approve each CloudShell action. Read what it is about to do, then approve it. Check that the reply names the site you meant. Every later result names the site too.

Step 5: Ask for a page and deploy it

Send this:

Create a page at /hello with a heading that says Hello from Gemini and one short
welcome paragraph. Save it as app/views/pages/hello.liquid and deploy it to the
selected instance with insites_deploy. Then check the deploy status and the logs.

Gemini writes the file in your project folder and sends it to CloudShell, which deploys it. Approve the deploy when Gemini asks.

Step 6: Check it is live

  1. Read Gemini's reply. It should show the deploy status as success and no errors in the logs.
  2. Open your site address with /hello on the end, for example https://my-staging-site.example.com/hello.
  3. You should see your heading and paragraph.

If the page does not appear, ask Gemini: Check the logs on the selected site for errors and fix them.

Step 7: Undo a change

When a deploy replaces a file that was already there, CloudShell keeps a copy of the old file for 30 days. To roll back, ask Gemini:

Show my recent deployments on the selected instance and restore the previous
version of app/views/pages/hello.liquid.

To remove the test page, ask Gemini to delete app/views/pages/hello.liquid. Every change also shows in the Console change log, with who made it.

If something goes wrong

  • A tool is refused. Your role on that site is too low. Ask the account owner to give you the Developer role in the Console.
  • The wrong site changed. Ask Gemini which site is selected before you deploy. See Working on Several Sites.
  • Gemini does not use CloudShell. Type /mcp list. Disabled means the folder is not trusted; Disconnected means you have not signed in (Step 2).
  • The sign-in has expired. Type /mcp auth insites-cloudshell again.
  • Gemini keeps making the same mistake. See When your AI gets stuck.

Related