Skip to main content

​
Overview

Intuned allows you to develop your projects using the Intuned online IDE or locally using Intuned’s CLI. This guide focuses on local development using the CLI. You should use local development when:
  • You want to use your own IDE instead of Intuned’s online IDE.
  • You want to manage the project with version control (e.g., Git) for better collaboration and versioning.
  • You want to use your own development tools, extensions, and AI tools.
  • You’re not planning to use Intuned Agent.
For the browser-based approach, see Online IDE.

​
Create a project

To create a new Intuned project locally, run: 
npx create-intuned-project@latest
Requires Node.js and npm.
Run with -h to see all available options.
The command walks you through project creation: selecting a language (TypeScript or Python), choosing a starter template, setting the project name, and connecting to your workspace. Once the project is created, you can expect the following structure: 
// api
// └── ...
// auth-sessions (if AuthSessions are enabled)
// └── check.ts
// └── create.ts
// Intuned.jsonc (Intuned settings file)
// package.json (dependencies)
// README.md 
// tsconfig.json
// yarn.lock

​
Intuned settings file (Intuned.jsonc)

The Intuned settings file contains the configuration settings for your project, including AuthSessions, replication settings, and more. For local projects, this includes your workspace ID and project name. Workspace ID and project name are required to save and deploy your project to Intuned. If provided during project creation, they’re saved in the Intuned settings file automatically. Otherwise, add them manually later.
Intuned.jsonc
{
  "projectName": "<your-project-name>",
  "workspaceId": "<your-workspace-id>",
  // ...
}
Alternatively, you can pass them to each command as arguments/options. Run the respective command with -h to see the available options.
By default, the Intuned settings file is Intuned.jsonc (JSON with comments). If you want to use a different format, you can pass --settings-format <settings-format> to the create command. For more info, run with -h.
For more information on the settings file and its options, refer to Intuned settings file.

​
API Key

An API key is required to save and deploy your project to Intuned. If provided during project creation, it’s saved to a .env file automatically.
.env
INTUNED_API_KEY=<your-api-key>
Otherwise, create this file manually or set it as an environment variable: 
export INTUNED_API_KEY=<your-api-key>
Keep your API key secure. Don’t expose it publicly or commit it to version control.
For more information on managing API keys, refer to Manage API keys.

​
Local development workflow

Use any IDE or text editor to develop your project locally. Install your project’s dependencies first, then confirm the CLI works by running: 
yarn intuned -h
The recommended dependency managers are yarn (v1) for TypeScript projects and uv for Python projects.

​
Understand the project structure

The api directory contains your browser automation APIs. Create new APIs by adding new files in this directory, which can be nested. An example for a social media RPA project: 
// api/
// ├── messages/
// │   ├── send.ts
// │   └── react.ts
// └── posts/
//     ├── react.ts
//     ├── reply.ts
//     └── share.ts

// Available APIs:
//  messages/send
//  messages/react
//  posts/react
//  posts/reply
//  posts/share

​
Write APIs

Implement your APIs using any functions, classes, or design patterns you prefer. The entry point for each API is defined as follows:
api/example.ts

// The default export is the entry point for the API

export default async function automation(
    params: any,
    page: Page,
    context: BrowserContext
) {
    // Your automation code here
    return {}; // Return results
}
Define other directories and files to import from and use in your APIs as needed.

​
Run APIs

Run an API: 
yarn intuned run api <api> <params>
Run with -h or check out CLI Reference to see all available options.

​
Debug APIs

If the API isn’t running as expected, use the --keep-browser-open flag to keep the browser open for debugging. Use the --trace flag to generate a trace, which you can open with Playwright’s trace viewer. Open the trace with: 
npx playwright show-trace <trace-file>

​
Work with AuthSessions

AuthSessions are reusable authentication sessions that can be used across multiple APIs. They help manage authentication flows and store session data securely. For more information, refer to AuthSessions (authenticated automation).
If you use a starter template that includes AuthSessions, the project comes with an AuthSession test-auth-session you can use directly.

​
AuthSession directories

During local development, projects using AuthSessions have two additional directories:
  • auth-sessions: Contains the create and check functions for AuthSessions.
  • auth-session-instances: Contains the stored AuthSession instances. Each instance is stored in a separate directory with its ID as the directory name.
The auth-session-instances directory is only used during local development. When deployed, AuthSession data is stored securely and encrypted on Intuned’s infrastructure.
// auth-sessions/
// ├── create.ts
// └── check.ts
// auth-session-instances/
// ├── test-auth-session/ # test-auth-session is an id for an AuthSession 
// └── auth-session-2/    # auth-session-2 is an id for an AuthSession

​
Write the create function

Inside auth-sessions/create, write code that creates your AuthSession (e.g., logging in). The create function doesn’t return anything—the browser state is captured after it completes.
auth-sessions/create.ts
export default async function create(
    page: Page,
    params: any,
    context: BrowserContext
) {
    // Your authentication code here
}

​
Write the check function

Inside auth-sessions/check, write code to verify the AuthSession is valid (e.g., checking the profile page to confirm you’re logged in). Check doesn’t take parameters and returns a boolean indicating whether the session is valid.
auth-sessions/check.ts
export default async function check(
    page: Page,
    context: BrowserContext
): Promise<boolean> {
    // Your session validation code here
    return true; // Return true if valid, false otherwise. Error will also be treated as invalid.
}

​
Manage AuthSessions

Create an AuthSession: 
yarn intuned run authsession create <auth-session> <params> --id <id>
Validate an AuthSession: 
yarn intuned run authsession validate <id>
Update an existing AuthSession: 
yarn intuned run authsession update <id> --parameters <new-parameters>
Run with -h or check out the CLI Reference to see all available options.

​
Run APIs with AuthSessions

When AuthSessions are enabled, APIs require an AuthSession ID to run: 
yarn intuned run api <api> <params> --auth-session <auth-session-id>

​
Use Runtime SDK and browser SDK helpers

Some helpers from Intuned Runtime SDK and Browser SDK require setting up your project on Intuned before use. This is because they need backend resources which we cannot access unless a project is created. You’ll see one of the following messages when you try to use them without setup: 
Unauthorized backend function call - make sure to save your project to Intuned to set up the correct API credentials

API credentials not set - make sure to save your project to Intuned to set up the correct API credentials.
Resolve this by saving your project to Intuned: 
yarn intuned save
If you don’t have your project name and workspace ID set in the Intuned settings file, provide them as arguments/options.

​
Deploy your project

When your project is ready, deploy it: 
yarn intuned deploy
After deployment succeeds, follow the output links for next steps.
If you don’t have your project name and workspace ID set in the Intuned settings file, provide them as arguments/options.

​
Set up CI/CD

Integrate Intuned deployment into your CI/CD pipelines with the CLI. Use the following command in your pipeline scripts: 
yarn intuned deploy --api-key <api-key>
Alternatively, set the INTUNED_API_KEY environment variable in your CI/CD environment to avoid passing the API key directly.

​
When to use IDE vs CLI

FeatureOnline IDELocal CLI
SetupZero setup, browser-basedRequires Python or Node runtime and Intuned CLI
Use caseUse Intuned Agent to build and edit scrapers
Use platform-specific features like stealth and captcha solving
Quick prototyping		Integrating your own CI/CD with version control and predefined team workflows
Version controlNo Git integration
Use built-in deployment tracking and history management		Full Git workflow that works with your team and your own repo
CollaborationSingle developer (no concurrent editing)Multiple developers with version control
IDE choiceIntuned’s web-based editorUse your preferred IDE (VS Code, JetBrains, etc.)

CLI reference

Complete CLI command documentation

How Intuned works

Understand Intuned’s architecture and execution model

AuthSessions

Build authenticated automations

Online IDE

Build automations with zero setup