webskillet

TypeScript client SDK and CLI for Webskillet runs.

• Client SDK: import { WebskilletClient } from "webskillet/client-sdk".
• CLI: webskillet <command>.

Install

# Use the CLI without installing
npx webskillet <command>

# Or add the package to your project
npm install webskillet

Client SDK

import { WebskilletClient } from "webskillet/client-sdk";

const client = new WebskilletClient({
  apiKey: process.env.WEBSKILLET_API_KEY!,
});

const result = await client.runs.run(
  {
    task: "Extract the title of example.com",
    startUrl: "https://example.com",
    skilletId: "example-title",
  },
  { timeoutMs: 30 * 60_000 }
);

console.log(
  result.status,
  result.status === "completed" ? result.result : undefined
);

Manage the lifecycle directly when you need custom polling:

const { id } = await client.runs.start({ task: "Extract the page title" });
const current = await client.runs.get(id);
const updated = await client.runs.update(id, { title: "Example page title" });
const recent = await client.runs.list({ limit: 20 });
const events = await client.runs.events(id);
const canceling = await client.runs.cancel(id);

runs.cancel() returns the run as it stands when the request is accepted. Cancellation is asynchronous, so that run is usually not canceled yet — poll runs.get() if you need to observe the terminal state.

runs.run() polls until the run is completed or canceled. It has no default deadline. Pass timeoutMs to stop waiting after a fixed duration. A completed run with outcome: "failed" throws WebskilletRunFailedError.

Pass onProgress to follow the agent's steps as they happen. Each event is reported once, oldest first:

await client.runs.run(
  { task: "Extract the title of example.com" },
  { onProgress: (event) => console.log(event.message) }
);

The client also exposes the other v1 resources:

const skillets = await client.skillets.list();

const sessions = await client.authSessions.list();
const session = await client.authSessions.get(sessions[0].id);
const recording = await client.authSessions.record({
  name: "GitHub",
  startUrl: "https://github.com/login",
});

Authentication accepts { apiKey }, sent as x-api-key, or an async { getAccessToken } callback, sent as a bearer token.

CLI

webskillet auth login                  # interactive (prompts for a method)
webskillet auth login --browser        # browser flow, no prompt
webskillet auth login --api-key <key>  # save an API key, no prompt
webskillet auth status --json          # exits nonzero when not authenticated
webskillet auth logout

webskillet start "Extract the title" --start-url https://example.com
webskillet start "Extract the title" --skillet-id example-title
webskillet result <run-id>
webskillet run "Extract the title" --wait 5m
webskillet cancel <run-id>
webskillet list --limit 20

webskillet install-skill

install-skill installs the webskillet agent skill by running npx skills@latest add Intuned/skills --skill webskillet.

When stdin is not a TTY (agents, CI), auth login skips the prompt and starts the browser flow automatically.

run prints the agent's steps as it works, checking each one off as the run moves past it:

✔ Opened example.com
✔ Extracted the page title
⠹ Submitting the result (12.3s)

Add --json to return machine-readable output. run waits indefinitely unless you pass --wait. A timeout or failed run exits with a nonzero status. Step lines are suppressed under --json and --quiet.

Environment Variables

Variable	Purpose
WEBSKILLET_API_KEY	API key used by the SDK and CLI.