npm package: @nboard-dev/octus
Description: Octus CLI - AI-powered onboarding for engineering teams
Author: nBoard Team
Latest version: 0.3.1

# @nboard-dev/octus

[![npm version](https://img.shields.io/npm/v/%40nboard%2Foctus.svg)](https://www.npmjs.com/package/@nboard-dev/octus)
[![license](https://img.shields.io/npm/l/%40nboard%2Foctus.svg)](./LICENSE)

> AI-powered onboarding for engineering teams

```text
   ____       __            
  / __ \____/ /___  _______
 / / / / __/ __/ / / / ___/
/ /_/ / /_/ /_/ /_/ (__  ) 
\____/\__/\__/\__,_/____/  
```

## Install

```bash
npm install -g @nboard-dev/octus
```

Works on **macOS**, **Linux**, and **Windows**.

## Quick Start

```bash
# 1. Login with your API key
octus login

# 2. Initialize your repo
octus init .

# 3. Run onboarding
octus setup

# 4. Check status
octus doctor
```

Or do it all in one command:

```bash
octus init . --run-setup
```

## Commands

| Command | Description |
|---------|-------------|
| `octus login` | Authenticate with your API key |
| `octus logout` | Clear stored credentials |
| `octus ping` | Check connection & auth status |
| `octus config` | Show current configuration |
| `octus init [path]` | Initialize a repository |
| `octus setup [path]` | Run onboarding steps |
| `octus doctor [path]` | Health check your setup |
| `octus generate-profile` | Generate a draft profile |

## Migration from Python CLI

`@nboard-dev/octus` is the Node.js replacement for the original Python/Homebrew CLI.

What stays the same:
- command names (`octus login`, `octus init`, `octus setup`, `octus doctor`)
- local config directory: `~/.nboard/`
- repo-local files: `.octus.yaml`, `.octus/profile.json`, `.octusignore`

What changes:
- install with npm instead of Poetry/Homebrew
- Node.js 18+ is now the primary runtime
- AI profile generation uses `@anthropic-ai/sdk` when `ANTHROPIC_API_KEY` is set

## Setup Options

```bash
# Use a specific profile
octus setup --profile demo-node

# Skip confirmations (CI mode)
octus setup --turbo

# Resume a failed run
octus setup --resume

# Show detailed output
octus setup --verbose

# Custom timeout per step (seconds)
octus setup --timeout 600
```

## Init Options

```bash
# Clone a repo and init
octus init https://github.com/org/repo.git

# Clone to specific directory
octus init https://github.com/org/repo.git -d my-folder

# Init and immediately run setup
octus init . --run-setup
```

## Configuration

Octus stores config in `~/.nboard/`:

```text
~/.nboard/
├── config.json             # API key & backend URL
├── approved_profiles.json  # Profile approval records
└── state/
    ├── run_state.json      # Current run progress
    └── run.lock            # Prevents concurrent runs
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `OCTUS_API_TOKEN` | API key (overrides config file) |
| `OCTUS_API_URL` | Backend URL (overrides config file) |
| `ANTHROPIC_API_KEY` | Enables AI-generated onboarding profiles during `octus init` |

## Repository Files

Octus creates these files in your repo:

| File | Purpose |
|------|---------|
| `.octus.yaml` | Signed init file from backend |
| `.octus/profile.json` | Local onboarding profile |
| `.octusignore` | Files to exclude from AI context |

## Requirements

- Node.js 18+
- Git

## Troubleshooting

### `Not logged in`

```bash
octus login
```

### `.octus.yaml not found`

```bash
octus init .
```

### AI profile generation fell back to rule-based mode

```bash
export ANTHROPIC_API_KEY=...
octus init .
```

### Backend/auth problems

```bash
octus config
octus ping
```

### Resume a blocked/interrupted onboarding run

```bash
octus setup --resume
```

## Links

- [Documentation](https://docs.nboard.tech/cli)
- [Dashboard](https://demo.nboard.tech)
- [Support](mailto:support@nboard.tech)

## License

MIT © nBoard Team