# 🚀 Getting Started

There are two ways to install ApexEloquent, and both deliver the exact same source. For a full comparison of the two paths (test execution during deploys, coverage calculation), see [Installing Apex Stem](/apex-stem/docs/apex-stem-installation).

| Path | Best for | Prerequisites |
|---|---|---|
| **Unlocked Package (recommended)** | New projects, production orgs | Salesforce CLI and an org login — nothing else |
| **Git Submodule** | Projects already on submodules, or when you need the v2 line | Everything in [Prerequisites](/apex-stem/docs/apex-eloquent-prerequisites), including make |


## 📦 Install as an Unlocked Package (recommended)

If you have finished the "Salesforce CLI Setup" and "Target Org" steps of the [Prerequisites](/apex-stem/docs/apex-eloquent-prerequisites), one command is all it takes. No make setup required.

```bash
$ sf package install -p 04tgK000000HaGnQAK -o <your-org> -w 10
```

To install from the browser instead, open `https://login.salesforce.com/packaging/installPackage.apexp?p0=04tgK000000HaGnQAK` (use `test.salesforce.com` for sandboxes).

The current version is **v3.5.0**. Install IDs for every release are listed on the [GitHub Releases](https://github.com/krile136/ApexEloquent/releases) page.

Installed as a package, ApexEloquent's bundled tests are **excluded from `RunLocalTests`**, and its code is **excluded from your org's coverage calculation** — failures caused by org-specific settings simply cannot happen.

:::warning
Only the **v3 line** is distributed as a package. On v3, SOQL and DML default to user mode (respecting FLS), so dropping it into an existing org can start failing on missing field permissions. If you need the v2 line (system-mode default), use the Git Submodule path below with the maintenance branch. See the top of the [ApexEloquent guide](/apex-stem/docs/apex-eloquent-guide) for what to weigh.
:::

### Updating

Run the same command with the next version's install ID — the installed package upgrades in place. Check what is installed with `sf package installed list -o <your-org>`.


## 📥 Install as a Git Submodule

### Package Acquisition (First Time Only)

```bash
$ cd force-app/main/default/classes
$ git submodule add https://github.com/krile136/ApexEloquent.git ApexEloquent
```

This will add the `ApexEloquent` directory to your repository and incorporate it into source control. If you are cloning a repository that already has it, don't forget `git submodule update --init --recursive`.

### Choosing the v2 line

The command above tracks the default branch (`main`), which gives you the **v3 line**. If you want to start on the v2 line, point at the maintenance branch.

```bash
$ git submodule add -b v2.2.x https://github.com/krile136/ApexEloquent.git ApexEloquent
```

Feature-wise it matches the v3 line; the only difference is the execution mode.

### Deploy to Organization

With all [Prerequisites](/apex-stem/docs/apex-eloquent-prerequisites) in place, deploy the acquired classes:

```bash
$ make install
```

The `make install` command internally calls Salesforce CLI deploy commands.

On the submodule path, ApexEloquent's bundled tests run as local tests and contribute to the 75% coverage requirement. However, **if test failures occur due to organization settings or disabled standard fields**, adjust the `*_T.cls` test classes accordingly — or consider switching to the Unlocked Package path.

### Updating

Run the following commands from your project root:

```bash
$ cd force-app/main/default/classes/ApexEloquent
$ git pull
$ make install
```

:::warning
`git pull` takes the tip of whatever branch you are tracking. **If you are on the v2 line (`v2.2.x`), switching to `main` and pulling will jump you to the v3 line.** That changes the default execution mode — a breaking change — so check what you are tracking with `git branch --show-current` before updating.
:::

:::warning
Submodules maintain information (pointers) about which commit the parent repository references.
To ensure consistency in production environments, we recommend using `git submodule update --remote` to automatically update the reference to the latest version,
and then committing in the parent repository as well.
:::


## 🔗 Back to Guide

← [Back to ApexEloquent Developer Guide](/apex-stem/docs/apex-eloquent-guide)