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

# Initialize a workspace

> Bootstrap a new workspace from the terminal with the guided onboarding wizard.

Flags and arguments below are the contract as the binary states it. The global flags (`--json`, `--timeout`, …) apply here too and are documented on [Global flags](/docs/cli/contract/global-flags). Error codes are a workspace-global contract, not a per-command one — the taxonomy, and how to read a code that is not in it, is on [The error envelope](/docs/cli/contract/error-envelope).

## `octolens init`

Guided onboarding: company profile, keywords, filters, and your first feed

Headless (`--json`, or no TTY) it never prompts: it reports the onboarding plan and exits `0` whether or not steps remain — read `fullyOnboarded` and `steps[].done` for what is left, never the exit code.

**Examples**

```bash theme={null}
octolens init
octolens init --json
```

**Returns**

With `--json`, stdout carries one JSON document with these fields.

| Field              | Type                                           | Description                                                                                                |
| ------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `interactive`      | boolean                                        | Always `false` in `--json`/headless mode — no prompts were opened; the payload is the plan.                |
| `fullyOnboarded`   | boolean                                        | `true` when every onboarding step is satisfied. The exit code stays `0` either way — branch on this field. |
| `steps`            | object\[]                                      | The onboarding steps, in journey order.                                                                    |
| `steps[].id`       | enum: `company`, `keywords`, `filters`, `feed` | Stable step identifier.                                                                                    |
| `steps[].title`    | string                                         | Imperative step title.                                                                                     |
| `steps[].done`     | boolean                                        | Whether the observable workspace state satisfies this step.                                                |
| `steps[].status`   | string                                         | One-line description of the current state.                                                                 |
| `steps[].commands` | string\[]                                      | The exact command(s) a non-interactive caller runs to complete the step.                                   |

A step may additionally carry a non-gating `tip` (`{status, commands}`) naming optional follow-up state (e.g. pending AI keyword suggestions); tips never affect `fullyOnboarded`.

Without `--json`: A terminal walks the pending steps interactively and prints a closing summary.

<Accordion title="Example output">
  ```json theme={null}
  {
    "interactive": false,
    "fullyOnboarded": false,
    "steps": [
      {
        "id": "company",
        "title": "Review your company profile",
        "done": true,
        "status": "Profile filled from acme.com.",
        "commands": [
          "octolens company get"
        ]
      },
      {
        "id": "keywords",
        "title": "Track your first keywords",
        "done": false,
        "status": "No keywords tracked yet.",
        "commands": [
          "octolens keywords add --term 'acme corp'"
        ]
      }
    ]
  }
  ```
</Accordion>

**Exit codes** — `0` OK · `1` UNEXPECTED · `2` USAGE · `8` CANCELLED. The full map is on [Exit codes](/docs/cli/contract/exit-codes).