> ## Documentation Index
> Fetch the complete documentation index at: https://www.adjar.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Adjar Quick Start

This guide connects an ad account to Adjar, exports it as plain-text config, and walks your first change through the full loop — ask, review, apply, measure. It works the same for **Google Ads** and **OpenAI Ads**; where a command differs, pick your platform's tab. The whole process takes about 10 minutes.

## Prerequisites

Before you begin, make sure you have:

* The `adjar` CLI installed
* An ad account you want to manage, with API access — [Google Ads](/docs/google-ads-api-access) or [OpenAI Ads](/docs/openai-ads-api-access)
* An AI agent or assistant (Claude Code, Cursor, or any other)

## Install the CLI

macOS (Apple silicon + Intel):

```bash theme={null}
curl -fsSL https://adjar.ai/install.sh | bash
```

This downloads the standalone `adjar` binary, verifies its checksum, and installs it to `~/.local/bin` — no Node or other runtime required.

<Note>
  macOS only for now. Linux and Windows builds are on the way.
</Note>

Verify the installation:

```bash theme={null}
adjar --version
```

## Set up credentials

Each platform has its own credentials file. Produce yours, then point Adjar at it.

<Tabs>
  <Tab title="Google Ads">
    Follow [Get Google Ads API access](/docs/google-ads-api-access) to produce your `google.json` file, then point Adjar at it:

    ```bash theme={null}
    export ADJAR_CREDENTIALS=/path/to/google.json
    ```

    Or pass `--credentials /path/to/google.json` on any command. Your **account ID** is the `customer_id` in that file — you'll pass it to `adjar import` next.
  </Tab>

  <Tab title="OpenAI Ads">
    Follow [Get OpenAI Ads API access](/docs/openai-ads-api-access) to produce your `openai.json` file, then point Adjar at it:

    ```bash theme={null}
    export ADJAR_CREDENTIALS=/path/to/openai.json
    ```

    Or pass `--credentials /path/to/openai.json` on any command. Your **account ID** looks like `adacct_…` — read it off the OpenAI Ads dashboard or the `ad_account` endpoint.
  </Tab>
</Tabs>

## The loop: ask, review, apply, measure

Adjar replaces the ad console with a config-driven workflow. Your account lives as plain-text TOML in your repo, your AI agent edits it, and the `adjar` CLI turns the diff into a reviewable plan it applies only when you approve. The performance report Adjar pulls back becomes your next ask.

Import your account once, then run the loop.

<Steps>
  <Step title="Import your account">
    Export your entire account into local TOML config. Replace `<id>` with your account ID.

    <Tabs>
      <Tab title="Google Ads">
        ```bash theme={null}
        adjar import --account <id> -o config/google.toml
        ```

        Adjar writes every campaign, ad group, keyword, and creative into `config/google.toml` as plain text you can version-control.
      </Tab>

      <Tab title="OpenAI Ads">
        ```bash theme={null}
        adjar import --platform openai --account <id> -o config/openai.toml
        ```

        Adjar writes every campaign, ad group, and ad into `config/openai.toml` as plain text you can version-control.
      </Tab>
    </Tabs>

    Re-run it anytime to refresh the file from the live account.

    <Tip>
      Large accounts can be split across multiple files with a top-level `imports` directive. See the config reference for [Google Ads](/docs/config/google/account) or [OpenAI Ads](/docs/config/openai/account).
    </Tip>
  </Step>

  <Step title="Commit your config">
    Add the config to version control. This is the baseline — every future change shows up as a diff against it.

    ```bash theme={null}
    git add config/
    git commit -m "chore: initial adjar config export"
    ```

    <Tip>
      Store your config in the same repo as your website or app, so your AI agent already has the context it needs when you ask it to work on ads.
    </Tip>
  </Step>

  <Step title="Ask your agent to make a change">
    Open your AI agent and tell it what you want in plain language. It reads your config, then edits the TOML directly — no special prompt engineering, the format is self-describing.

    ```
    "Pause every campaign that spent more than $50 this month
     with zero conversions."
    ```

    ```
    ● Read config/google.toml
    ● Edited config/google.toml
       1 campaign status "active" → "paused"
    ```
  </Step>

  <Step title="Review the plan">
    Before anything touches your live account, run `adjar plan`. Adjar compares your local config against the live account and prints every change as a diff. The platform is read from the config's `platform` field, so a single `--config` is all it needs:

    ```bash theme={null}
    adjar plan --config config/google.toml
    ```

    The plan shows:

    * Fields being changed, with old vs. new values
    * New campaigns, ad groups, keywords, or ads being created
    * Resources being paused or removed

    Nothing is applied until you approve.
  </Step>

  <Step title="Apply the changes">
    If the plan looks right, apply it:

    ```bash theme={null}
    adjar apply --config config/google.toml
    ```

    Adjar executes the changes against the platform's API and writes the assigned IDs back into your config. Commit the result — your repo is now the source of truth:

    ```bash theme={null}
    git add config/
    git commit -m "feat: pause overspending campaigns with no conversions"
    ```

    <Note>
      Every change is a git commit. If an experiment underperforms, rollback is `git revert` — not a hunt through the console's change history.
    </Note>
  </Step>

  <Step title="Pull a performance report">
    Close the loop: `adjar report` pulls a month of performance as plain-text markdown, written right beside your config. Pass `--month` for a calendar month, or omit it to default to the last complete month.

    <Tabs>
      <Tab title="Google Ads">
        ```bash theme={null}
        adjar report --config config/google.toml --month 2026-05 -o reports/2026-05.google.md
        ```

        ```markdown theme={null}
        ## Campaigns
        | Campaign      | Clicks |   CTR |    Cost | Conv. |
        | ------------- | -----: | ----: | ------: | ----: |
        | Running Shoes |    140 | 2.90% | $182.40 |     6 |
        | Trail Shoes   |     86 | 1.74% | $121.10 |     2 |
        ```
      </Tab>

      <Tab title="OpenAI Ads">
        ```bash theme={null}
        adjar report --config config/openai.toml --month 2026-05 -o reports/2026-05.openai.md
        ```

        ```markdown theme={null}
        ## Campaigns
        | Campaign            | Impr. | Clicks |   CTR |  Spend |
        | ------------------- | ----: | -----: | ----: | -----: |
        | Database Governance | 8,000 |     40 | 0.50% | $140.00 |
        ```
      </Tab>
    </Tabs>

    <Tip>
      Need a single day instead? Pass `--day 2026-05-31`. It's mutually exclusive with `--month`.
    </Tip>

    Config and report are both plain text, so next round your agent reads them side by side — spotting what spends without converting before it proposes the next change. Commit it alongside your config, and the next ask starts here.
  </Step>
</Steps>

That's the full loop — and it repeats. Each round starts from the latest report.

## How the pieces fit together

| Piece                | What it does                                                   |
| -------------------- | -------------------------------------------------------------- |
| **TOML config**      | Declarative representation of your entire ad account           |
| **Markdown reports** | Performance data your agent can read                           |
| **`adjar import`**   | Exports your live account into TOML the first time             |
| **`adjar plan`**     | Compares local config to the live account; prints the diff     |
| **`adjar apply`**    | Executes the diff against the ad platform's API                |
| **`adjar report`**   | Pulls performance into a Markdown report                       |
| **Your AI agent**    | Reads config + reports, proposes edits, explains its reasoning |
| **You**              | Review every plan, approve what ships, provide judgment        |

## Next steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/docs/cli/overview">
    The core workflow plus full flags and options for every command.
  </Card>

  <Card title="Config Reference" icon="file-code" href="/docs/config/google/account">
    Understand every field in your TOML config — [Google Ads](/docs/config/google/account) and [OpenAI Ads](/docs/config/openai/account).
  </Card>

  <Card title="File Organization" icon="folder-tree" href="/docs/config/organization">
    How to split config across files and how `imports` composes them.
  </Card>

  <Card title="adjar report" icon="chart-line" href="/docs/cli/report">
    Pull performance into Markdown that closes the loop.
  </Card>
</CardGroup>