> ## Documentation Index
> Fetch the complete documentation index at: https://intunedhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

export const CLICommandTabs = ({command, withOptions = true}) => {
  if (!Array.isArray(command)) {
    command = [command];
  }
  function mapAliases(aliases) {
    return aliases.map((alias, index) => <>
        {alias}
        {index === 0 ? "" : " # Alias"}
        {"\n\n"}
      </>);
  }
  return <CodeGroup>
      <CodeBlock language="general" filename="General">
        {mapAliases(command.map(cmd => `${cmd}${withOptions ? " [options]" : ""}`))}
      </CodeBlock>

      <CodeBlock icon="python" language="uv" filename="uv">
        {mapAliases(command.map(cmd => `uv run ${cmd}${withOptions ? " [options]" : ""}`))}
      </CodeBlock>

      <CodeBlock icon="python" language="poetry" filename="poetry">
        {mapAliases(command.map(cmd => `poetry run ${cmd}${withOptions ? " [options]" : ""}`))}
      </CodeBlock>

      <CodeBlock icon="https://d3gk2c5xim1je2.cloudfront.net/devicon/typescript.svg" language="npm" filename="npm">
        {mapAliases(command.map(cmd => `npm run ${cmd}${withOptions ? " -- [options]" : ""}`))}
      </CodeBlock>

      <CodeBlock icon="https://d3gk2c5xim1je2.cloudfront.net/devicon/typescript.svg" language="yarn" filename="yarn">
        {mapAliases(command.map(cmd => `yarn ${cmd}${withOptions ? " [options]" : ""}`))}
      </CodeBlock>
    </CodeGroup>;
};

Develop your projects using Hosted projects in the online IDE or locally as Connected projects with the local CLI. This guide focuses on Connected projects and the local CLI.

Use local development when:

* You prefer 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 prefer working without Intuned Agent.

For the browser-based approach, see [Online IDE](./online-ide).

## Install the CLI

Install the Intuned CLI by following the [CLI installation guide](/main/02-features/cli#installation).

## Create a project

To create a new Intuned project locally, run:

<CodeGroup>
  ```txt CLI theme={null}
  intuned dev init
  ```

  ```txt npx theme={null}
  npx create-intuned-project@latest
  ```
</CodeGroup>

<Note>
  Requires Node.js and npm. Run with `-h` to see all available options.
</Note>

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:

<CodeGroup dropdown>
  ```typescript theme={null}
  // api
  // └── ...
  // auth-sessions (if AuthSessions are enabled)
  // └── check.ts
  // └── create.ts
  // auth-sessions-instances (if AuthSessions are enabled)
  // ├── test-authsession/
  // └── ...
  // intuned-resources
  // ├── auth-sessions/ (if AuthSessions are enabled)
  // │   └── test-authsession.auth-session.jsonc
  // └── jobs/
  //     └── default.job.jsonc
  // Intuned.jsonc (Intuned settings file)
  // package.json (dependencies)
  // README.md
  // tsconfig.json
  // yarn.lock
  ```

  ```python theme={null}
  #  api
  #  └── ...
  #  auth-sessions (if AuthSessions are enabled)
  #  └── check.py
  #  └── create.py
  #  auth-sessions-instances (if AuthSessions are enabled)
  #  ├── test-authsession/
  #  └── ...
  #  intuned-resources
  #  ├── auth-sessions/ (if AuthSessions are enabled)
  #  │   └── test-authsession.auth-session.jsonc
  #  └── jobs/
  #      └── default.job.jsonc
  #  Intuned.jsonc (Intuned settings file)
  #  pyproject.toml (dependencies)
  #  README.md
  #  uv.lock
  #
  ```
</CodeGroup>

### 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.

```jsonc Intuned.jsonc theme={null}
{
  "projectName": "<your-project-name>",
  "workspaceId": "<your-workspace-id>"
  // ...
}
```

Or pass them to each command as arguments. Run the respective command with `-h` to see the available options.

<Note>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`.</Note>

For more information on the settings file and its options, refer to [Intuned settings file](../05-references/intuned-json).

## Authenticate

Authenticate to Intuned by following the [CLI authentication guide](/main/02-features/cli#authentication). This allows you to save and deploy your project, and use CLI features that require authentication.

## Local development workflow

Use any IDE or text editor to develop your project locally. Start by installing your project's dependencies.

<Tip>
  The recommended dependency managers are `yarn` (v1) for TypeScript projects
  and `uv` for Python projects.
</Tip>

### 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:

<CodeGroup dropdown>
  ```typescript theme={null}
  // 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
  ```

  ```python theme={null}
  #  api/
  #  ├── messages/
  #  │   ├── send.py
  #  │   └── react.py
  #  └── posts/
  #      ├── react.py
  #      ├── reply.py
  #      └── share.py
  #
  #  Available APIs:
  #   messages/send
  #   messages/react
  #   posts/react
  #   posts/reply
  #   posts/share
  ```
</CodeGroup>

### Write APIs

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

<CodeGroup dropdown>
  ```typescript api/example.ts theme={null}
  // 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
  }
  ```

  ```python api/example.py theme={null}
  # The function named `automation` is the entry point for the API

  async def automation(
      page: Page,
      params: Any | None = None,
      **kwargs
  ):
      # Your automation code here
      return {} # Return results
  ```
</CodeGroup>

Define other directories and files to import from and use in your APIs as needed.

### Run APIs

Run an API:

<CLICommandTabs command="intuned dev run api <api> <params>" withOptions={false} />

<Tip>
  Run with `-h` or check out [CLI Reference](../05-references/cli/overview) to
  see all available options.
</Tip>

### 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 shared across multiple APIs. They manage authentication flows and store session data securely. For more information, refer to [AuthSessions (authenticated automation)](./auth-sessions).

<Note>
  If you use a starter template that includes AuthSessions, the project comes
  with an AuthSession instance called `test-authsession` that you can find under
  the `auth-sessions-instances` directory.
</Note>

#### 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.

<Note>
  The `auth-session-instances` directory is only used during local development.
  When deployed, AuthSession data is stored securely and encrypted on Intuned's
  infrastructure.
</Note>

<CodeGroup dropdown>
  ```typescript theme={null}
  // auth-sessions/
  // ├── create.ts
  // └── check.ts
  // auth-session-instances/
  // ├── test-authsession/ # test-authsession is an id for an AuthSession
  // └── auth-session-2/    # auth-session-2 is an id for an AuthSession
  ```

  ```python theme={null}
  # auth-sessions/
  # ├── create.py
  # └── check.py
  # auth-session-instances/
  # ├── test-authsession/ # test-authsession is an id for an AuthSession
  # └── auth-session-2/    # auth-session-2 is an id for an AuthSession
  ```
</CodeGroup>

#### 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.

<CodeGroup dropdown>
  ```typescript auth-sessions/create.ts theme={null}
  export default async function create(
    page: Page,
    params: any,
    context: BrowserContext
  ) {
    // Your authentication code here
  }
  ```

  ```python auth-sessions/create.py theme={null}
  async def create(
      page: Page,
      params: Any | None = None,
      **kwargs
  ):
      # Your authentication code here
      ...
  ```
</CodeGroup>

#### 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). The check function takes no parameters and returns a boolean indicating whether the session is valid.

<CodeGroup dropdown>
  ```typescript auth-sessions/check.ts theme={null}
  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.
  }
  ```

  ```python auth-sessions/check.py theme={null}
  async def check(
      page: Page,
      **kwargs
  ) -> bool:
      # Your session validation code here
      return True  # Return True if valid, False otherwise. Exception will also be treated as invalid.
  ```
</CodeGroup>

#### Manage AuthSessions

**Create an AuthSession:**

<CLICommandTabs command="intuned dev run authsession create <params> --id <id>" withOptions={false} />

**Validate an AuthSession:**

<CLICommandTabs command="intuned dev run authsession validate <id>" withOptions={false} />

**Update an existing AuthSession:**

<CLICommandTabs command="intuned dev run authsession update <id> --input <new-parameters>" withOptions={false} />

<Tip>
  Run with `-h` or check out the [CLI Reference](../05-references/cli/overview)
  to see all available options.
</Tip>

#### Run APIs with AuthSessions

When AuthSessions are enabled, APIs require an AuthSession ID to run:

<CLICommandTabs command="intuned dev run api <api> <params> --auth-session <auth-session-id>" withOptions={false} />

### Use Runtime SDK and browser SDK helpers

Some helpers in the Intuned Runtime SDK and Browser SDK need backend resources that are only available after you provision your project. Without provisioning, you'll see one of these messages:

```
Unauthorized backend function call - make sure to provision your project to Intuned to set up the correct API credentials

API credentials not set - make sure to provision your project to Intuned to set up the correct API credentials.
```

Resolve this by provisioning your project to Intuned:

<CLICommandTabs command="intuned dev provision" withOptions={false} />

<Note>
  If you don't have your project name and workspace ID set in the Intuned
  settings file, provide them as arguments/options.
</Note>

## Deploy your project

When your project is ready, deploy it:

<CLICommandTabs command="intuned dev deploy" withOptions={false} />

After deployment succeeds, follow the output links for next steps.

<Note>
  If you don't have your project name and workspace ID set in the Intuned
  settings file, provide them as arguments/options.
</Note>

### Set up CI/CD

Integrate Intuned deployment into your CI/CD pipelines with the CLI. Set `INTUNED_API_KEY` in your CI/CD environment.

<CodeGroup>
  ```yaml GitHub Actions (TypeScript) icon="github" theme={null}
  name: Deploy to Intuned
  on:
    push:
      branches:
        - main
  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
        - name: Set up Node.js
          uses: actions/setup-node@v2
          with:
            node-version: '24'
        - name: Install Intuned CLI
          run: npm install -g @intuned/cli
        - name: Install dependencies
          run: yarn install
        - name: Deploy to Intuned
          env:
            INTUNED_API_KEY: ${{ secrets.INTUNED_API_KEY }}
          run: intuned dev deploy --non-interactive
  ```

  ```yaml GitHub Actions (Python) icon="github" theme={null}
  name: Deploy to Intuned
  on:
    push:
      branches:
        - main
  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
        - name: Set up Node.js
          uses: actions/setup-node@v2
          with:
            node-version: "24"
        - name: Set up Python
          uses: actions/setup-python@v5
          with:
            python-version: "3.12"
        - name: Install uv
          run: pip install uv
        - name: Install Intuned CLI
          run: npm install -g @intuned/cli
        - name: Install dependencies
          run: uv sync
        - name: Deploy to Intuned
          env:
            INTUNED_API_KEY: ${{ secrets.INTUNED_API_KEY }}
          run: intuned dev deploy --non-interactive
  ```
</CodeGroup>

## When to use Hosted projects (online IDE) vs Connected projects (local CLI)

| Feature             | Hosted projects (online IDE)                                                                                                             | Connected projects (local CLI)                                                                             |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Setup**           | Zero setup, browser-based                                                                                                                | Requires Python or Node runtime and Intuned CLI                                                            |
| **Use case**        | Use Intuned Agent to build and edit scrapers<br />Use platform-specific features like stealth and captcha solving<br />Quick prototyping | Integrating your own CI/CD with version control and predefined team workflows                              |
| **Platform AI**     | Full access to platform AI features like **Fix with AI**, **Fix issues**, and **self-healing projects**                                  | Platform AI features like **Fix with AI**, **Fix issues**, and **self-healing projects** are not supported |
| **Version control** | No Git integration<br />Use built-in deployment tracking and history management                                                          | Full Git workflow that works with your team and your own repo                                              |
| **Collaboration**   | Single developer (no concurrent editing)                                                                                                 | Multiple developers with version control                                                                   |
| **IDE choice**      | Intuned's web-based editor                                                                                                               | Use your preferred IDE (VS Code, JetBrains, etc.)                                                          |

## Related resources

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/main/05-references/cli/overview">
    Complete CLI command documentation
  </Card>

  <Card title="How the platform works" icon="book" href="/main/00-getting-started/how-intuned-works">
    Understand Intuned's architecture and execution model
  </Card>

  <Card title="AuthSessions" icon="key" href="/main/02-features/auth-sessions">
    Build authenticated automations
  </Card>

  <Card title="Online IDE" icon="browser" href="/main/02-features/online-ide">
    Build automations with zero setup
  </Card>
</CardGroup>