Skip to main content
Let’s get you up and running with Cuehand in 60 seconds. It is important to note that Cuehand uses Gemini as the default model for AI interactions. You can use any other model supported by the Vercel AI SDK.
1

Create a sample project

Here we use the Cuehand CLI to create a sample project. For this guide just press Enter on your keyboard for all options to accept the defaults. If you want to learn more about the CLI, see the CLI page.
npx create-cuehand .
2

Add your API key

  1. Navigate to the Google AI Studio.
  2. Copy your API key.
  3. Paste your Google AI API key into your .env file.
.env
GOOGLE_GENERATIVE_AI_API_KEY="your-api-key"
3

Use Cuehand (act, extract, observe)

The scaffold includes an index.ts file that contains basic Cuehand code. Here’s what it looks like:
index.ts
import { Cuehand } from "cuehand";
import { z } from "zod";

async function main() {
  const cuehand = new Cuehand({
    type: "LOCAL",
    model: "google/gemini-2.5-flash",
  });

  await cuehand.init();

  await cuehand.goto("https://ollama.com/");

  const [action] = await cuehand.observe(
    "click the search bar at the top"
  );

  if (action) {
    await cuehand.act(action);
  };

  await cuehand.act("type 'gemini' into the search bar");

  await cuehand.act("press enter");

  await cuehand.wait(2);

  await cuehand.act("click the first result that shows up");

  const model = await cuehand.extract("get the model details",
    z.object({
      model: z.string().describe("the exact model name"),
      description: z.string().describe("the model description"),
      download: z.number().describe("the number of downloads"),
    })
  );

  console.log("Model: ", model);

  await cuehand.wait(10);

  await cuehand.close();
}

main();
4

Finally, run it

Run the project using the following command:
npm start
That’s it! You have successfully created and run your first Cuehand project. 🎉