# Salesforce CLI Org Launcher - End User Installation

Crafted with ❤️ by [Kiran Markad](https://www.linkedin.com/in/kiranmarkad).

Use this guide after the extension is published in the Chrome Web Store.

## What This Extension Needs

- Google Chrome or a Chromium-based browser.
- Node.js 20 or later.
- Salesforce CLI installed and available as `sf` or `sfdx`.
- The companion native-host installer package from your administrator or publisher.

Chrome Web Store installs the browser extension only. Because this extension reads local Salesforce CLI orgs, each machine must run the companion native-host installer once.

## Install From Chrome Web Store

1. Open the Salesforce CLI Org Launcher listing in the Chrome Web Store.
2. Click **Add to Chrome**.
3. Confirm the install prompt.
4. After install, Chrome opens a setup page or the extension popup.

## Install The Companion Native Host

Download and unzip:

```text
SalesforceOrgLauncher-portable-mac-windows-linux.zip
```

### macOS

1. Open Terminal.
2. Go to the unzipped package folder.
3. Run:

```bash
chmod +x install-mac-linux.sh
./install-mac-linux.sh
```

### Linux

1. Open Terminal.
2. Go to the unzipped package folder.
3. Run:

```bash
chmod +x install-mac-linux.sh
./install-mac-linux.sh
```

### Windows

Recommended installer:

1. Download `SalesforceCliOrgLauncherCompanionSetup.exe`.
2. Double-click the installer.
3. Finish the setup wizard.
4. Open Chrome and click the extension icon.
5. Click **Refresh**.

Manual fallback:

1. Open PowerShell.
2. Go to the unzipped package folder.
3. Run:

```powershell
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
```

## First Launch

1. Open Chrome.
2. Click the Salesforce CLI Org Launcher extension icon.
3. Click **Refresh**.
4. Confirm your Salesforce CLI orgs appear.
5. Click **Open** on an org to launch Salesforce in a new tab.

## Using Groups

1. Enter a group name under **My org groups**.
2. Click **Create Group**.
3. On any org card, choose a group and click **Add**.
4. The group is saved locally and appears the next time the extension opens.
5. Use **Remove from Group** or **Delete Group** when needed.

## macOS Folder Permission Prompt

macOS may ask whether `native-launcher` can access Desktop, Documents, Downloads, or another protected folder. This is an Apple privacy prompt.

- Allow access if your Salesforce projects are stored in that folder.
- The extension does not rescan folders every time it opens.
- Folder scanning happens when you click **Refresh** or save changed project roots.

## Expired Orgs

The launcher shows Salesforce CLI authenticated orgs quickly. If an org session is expired, the org may still appear, but clicking **Open** shows a clear re-authorization message.

To fix an expired org, run Salesforce CLI auth again, for example:

```bash
sf org login web --alias <alias>
```

Then open the extension and click **Refresh**.

## Troubleshooting

- If the popup says native host is missing, run the companion installer again.
- If no orgs appear, confirm `sf org list` works in Terminal or PowerShell.
- If an org does not open, re-authorize that org with Salesforce CLI.
- If project grouping looks incomplete, open **Settings**, add the folder where your Salesforce projects live, save, and click **Refresh**.
