---
title: Onboarding paths
description: Build guided first tasks for new members on Venom Cloud, and walk them with venom onboard.
section: reference
order: 170
audience: [operator, user]
sources: [docs/onboarding.md, cli/src/onboard.ts, services/nodejs-cloud/lib/onboarding]
features: [reference.doc-onboarding]
---

An admin builds a path of ordered steps on the team's own repositories: read the tour, run the tests, fix a good first issue, ship a small pull request. The new member sees it as a checklist in the console's Onboarding page and walks it with `venom onboard`, which starts each step.

```bash
venom onboard              # the paths and where you are
venom onboard next         # start the next step
venom onboard done <step>  # tick a manual step
```

## Steps {#steps}

| Kind | What it is | `venom onboard next` does |
|---|---|---|
| `tour` | Read the architecture tour | Runs `venom tour` and marks the step done when it finishes. |
| `template` | Start from a template, with arguments | Starts a session as `venom new <template> <args>`. |
| `task` | A starter task | Starts a session whose first message is the step's prompt. |
| `issue` | Take an issue | Says what to do. |
| `pr` | Ship a pull request | Says what to do. |

Each step names what shows it is done:

| Signal | Done when |
|---|---|
| `manual` | The member says so, in the console or with `venom onboard done <step>`. |
| `session` | A session of theirs ended. |
| `edit` | Such a session changed files. |
| `pr_merged`, `issue_closed` | The member's venom reported a merged pull request or a closed issue. These need `tasks.lookup: gh` in their `venom.yaml`; the cloud never asks GitHub itself. |

Signals come from what the cloud already holds, attributed through the member's own keys, and count only work after the path was created and the member joined. A step seen once stays done.

## Building a path {#building}

In the console's Onboarding page, members with `org:manage` create a path or start from a ready-made one ("Ship your first change", "Get oriented") and edit it. Steps can be reordered; removing a step drops its progress. Admins see every member's progress. At most 20 paths of 20 steps.

## API {#api}

| Call | What |
|---|---|
| `GET /v1/onboarding` | The key's member's paths with state, for the CLI. |
| `POST /v1/onboarding/steps` `{path_id, step_id, done?}` | Mark a manual step; an automatic one answers `409`. |
| `GET /api/admin/v1/onboarding` | Paths, the caller's progress, starters; every member's progress for `org:manage`. |
| `POST /api/admin/v1/onboarding`, `PATCH` and `DELETE /api/admin/v1/onboarding/paths/{id}` | Create, change, delete a path. The audit log records names and counts, never step text. |

The generated reference is at `/docs/api/cloud`.

## Related

- [Glossary](/docs/reference/glossary.md)
