Skip to content

feat(docs): add quickstart prerequisites and troubleshooting #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KumailQazi wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(docs): add quickstart prerequisites and troubleshooting #114

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion docs-site/docs/01-getting-started/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@ import TabItem from '@theme/TabItem';

Get AdaL running in 2 minutes.

## Prerequisites

Before you install, make sure you have:

- A supported terminal (iTerm2, VS Code terminal, Windows Terminal, or Linux terminal)
- **Node.js 20+** if you choose the npm install path
- A desktop browser available for first-run authentication

## Step 1: Install

Open any terminal — we recommend iTerm2, cmux, and VS Code terminal. macOS native Terminal requires macOS 26+ for full theme support. For more details, see [Terminal Setup](#terminal-setup).
Expand Down Expand Up @@ -44,7 +52,14 @@ Go to your working directory and run:
adal
```

First run opens browser for authentication, then you're ready.
First run opens a browser for authentication. After login completes, return to your terminal and start chatting.

### What success looks like

A successful first run means:
- The browser authentication flow completes
- You return to terminal and can submit prompts
- AdaL responds without authentication errors

## Step 3: Try It

Expand All @@ -56,6 +71,16 @@ First run opens browser for authentication, then you're ready.
> /init
```

## Common Issues

- **`adal: command not found`**
- Restart terminal, then run `which adal` to verify PATH.
- **Browser didn't open for auth**
- Copy/paste the auth URL manually into your browser and complete login.
- **npm install fails due to Node version**
- Check `node -v` and upgrade to Node.js 20+.
- **Colors look incorrect**
- See [Terminal Setup](#terminal-setup) and enable truecolor.

## Essential Commands

Expand Down