# Jules CLI Setup

## Installation

### Quick Install (Recommended)

Use our installation script:

```shell
bash scripts/install_jules.sh
```

This script will:
- Check Node.js version (requires >= 18.0.0)
- Install Jules CLI globally via npm
- Verify the installation
- Show next steps

### Manual Install

Alternatively, install directly with npm:

```shell
npm install -g @google/jules
```

## Authentication

Before you can use the tool, you must authenticate with your Google account.

```shell
jules login
```

This command will open a browser window to guide you through the Google authentication process.

## GitHub org + private repo access (required)

If you’re working in an **organization** (or on **private repositories**), you must also install/authorize the **Jules GitHub App** for the org. Installing it only on a personal account does **not** automatically grant access to org repos.

- **Install Jules on the org account (separately)**:
  - In GitHub, open the **organization** → **Settings** → **GitHub Apps** (or “Installed GitHub Apps”).
  - Find **Jules** and **Install** it for the org.
  - Choose **All repositories** or explicitly select the repos Jules should access.

- **Private repos need explicit permissions**:
  - For private repos, the GitHub App must be granted **repository access** and the required permissions.
  - In practice this commonly means allowing **full `repo` access/control** (or equivalent “Repository contents” + PR permissions), otherwise Jules will not be able to read/write PRs or fetch repo contents.

## Refresh Jules after GitHub authorization

After you install/approve the GitHub App permissions (especially changing org/private-repo access), refresh Jules so it re-reads the updated authorization state:

1. **Close and restart** Jules (exit the TUI, re-run `jules`, or re-run your `jules new ...` command).
2. If the newly-authorized repos still don’t appear or actions still fail, force a clean re-auth:

```shell
jules logout
jules login
```

## Quick verification

Use these commands to sanity-check connectivity after setup/authorization changes:

```shell
jules version
jules remote list --repo
```

## CI/CD Environment Setup

For automated environments (GitHub Actions, GitLab CI, etc.), authentication requires a token:

### 1. Get a Jules Token

First, authenticate locally and extract your token:

```shell
jules login
# After successful login, your token is stored
```

The token location varies by platform:
- **Linux/macOS**: `~/.config/jules/credentials`
- **Windows**: `%APPDATA%\jules\credentials`

### 2. Add Token to CI/CD Secrets

In your CI/CD platform (e.g., GitHub):
1. Go to repository **Settings** → **Secrets and variables** → **Actions**
2. Add new repository secret: `JULES_TOKEN`
3. Paste your token value

### 3. Use in Workflow

Example GitHub Actions workflow:

```yaml
name: Jules Automation

on: [push]

jobs:
  jules-task:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install Jules CLI
        run: npm install -g @google/jules
      
      - name: Run Jules Task
        env:
          JULES_TOKEN: ${{ secrets.JULES_TOKEN }}
        run: |
          # Jules will use JULES_TOKEN from environment
          jules remote list --repo
```

### Notes for CI/CD

- The npm package installs successfully in CI environments
- First `jules` command execution requires authentication (downloads binary)
- In sandboxed environments without authentication, the wrapper is installed but commands require valid credentials
- Use `JULES_TOKEN` environment variable for non-interactive authentication