--- name: anfra-setup-repo description: Set up a new Anfra repo — install the anfra CLI if needed, run `anfra init`, connect a data source, and get a first model and dataset validated and queried. Use when starting an Anfra project, connecting a database, or when a repo has no `.anfra/` config yet. --- # Setting up an Anfra repo An Anfra repo is a folder of AML (models and datasets), Data Apps, and a little config in `.anfra/`. Done means: the data source answers a query, `anfra validate` passes, and an AQL query returns rows from a dataset. ## 1. Check the CLI ```sh anfra version ``` If it is missing, install it, then call it by the path the installer prints if it is not on the `PATH` yet: ```sh curl -fsSL https://raw.githubusercontent.com/holistics/anfra/main/install.sh | bash ``` Ask before installing. Reuse a working CLI rather than upgrading it unless the user asks (`anfra update`). ## 2. Create the repo's files Ask the user whether they're starting a new repo, or joining one their org already publishes. `anfra init` sets up the repo's files. It creates what is missing and never changes an existing file beyond adding to it, so it is safe to run again: | Path | What it is | |---|---| | `.anfra/data_sources.yml` | The data sources to query, **with credentials**. Git-ignored. | | `.anfra/data_sources.yml.example` | The same without credentials, to commit, so a collaborator knows what to fill in. | | `.anfra/context_sources.yml` | What `anfra ingest` reads for `anfra search`: the repo's own AML. | | `models/`, `datasets/`, `apps/` | AML models, AML datasets, Data Apps. | | `.gitignore` | Gains `.anfra/data_sources.yml`. | | `AGENTS.md` | Gains the anfra block, telling coding agents to use the anfra skills (and `@AGENTS.md` in an existing `CLAUDE.md`). | ### Starting a new repo Before running `anfra init`, ask the user whether to add the e-commerce sample: 6 models, a dataset, a small DuckDB file and a Data App, so they can try anfra without a warehouse of their own. Ask first, because init writes `.anfra/data_sources.yml` and never changes it afterwards. Then run init once, from the repo's folder (an existing Git repo is fine): ```sh anfra init --example # the user wants the sample; or: anfra init --example anfra init --yes # they don't; or: anfra init --yes ``` With the sample, the repo already queries its DuckDB file: skip step 3 and run `anfra validate`. ### Joining the org's repo Don't offer the sample: the repo has its own models. - **If the team shares it through git,** clone it, and run `anfra init --yes` in the clone, which adds what isn't committed. The org's address is committed in `.anfra/config.yml`, so there's nothing to pull, and the committed `.anfra/data_sources.yml.example` names the data sources. - **Otherwise,** run `anfra init --yes` in a new folder, then bring the repo's files from the org, as below. Either way, once the repo's files are here, connect the data source (step 3) and query it (step 5). The models are already there, so skip step 4. #### Without git: pull from the org `anfra pull` needs the org's address, `https:///o/`. Find it with the user: 1. Run `anfra auth status`. It lists the orgs the user is signed in to on this machine, with their addresses. If one is the org, confirm it with the user. 2. Otherwise, ask the user to open the org in their browser, and paste the address of any of its pages, such as `https://bi.example.com/o/acme/dashboards/12`. anfra keeps only the org's part. 3. If the user knows only the server's address, run `anfra auth login https://`. The user chooses the org in the browser, and the login's result gives its address. Then pull, which saves the address as the repo's org (`org.url` in `.anfra/config.yml`): ```sh anfra pull --set-org https:///o/ ``` If it answers that the user isn't signed in, run `anfra auth login https:///o/`. It opens the user's browser, where they approve the sign-in, so tell them to look for it. Then pull again. Or ask the user to run `anfra pull` in their own terminal. There, it lists the orgs they're signed in to, lets them choose, and offers to sign in to another. Then carry on once they say it's done. The pull's hints name the data sources the repo uses that `.anfra/data_sources.yml` doesn't have, with their types. Add those in step 3. See [](../anfra-publish/) for pulling and publishing with others. ## 3. Connect the data source Ask the user which database, and for its connection details. Then replace the template's `warehouse` entry in `.anfra/data_sources.yml`: ```yaml data_sources: : # what models and datasets name in data_source_name type: # postgresql, snowflake, bigquery, ... see the reference connection: # keys depend on the type ... ``` **Read [references/data-sources.md](references/data-sources.md) for the type's exact keys.** They are easy to guess wrong (`dbname`, not `database`; `user`, not `username`; `port` a number; certificates and keys pasted in as text, not file paths), and a misspelled key is silently ignored. Credentials: - Write them only to `.anfra/data_sources.yml`, and check it is git-ignored (`git check-ignore .anfra/data_sources.yml`). Never echo a password back, put one in a commit, a log or your reply. - Mirror the entry in `.anfra/data_sources.yml.example` with placeholders (`password: `), so the committed file names the sources without their secrets. - Prefer a read-only database user. Anfra only reads, and a read-only login keeps an exploratory SQL query from changing anything. Check the connection with a trivial query: ```sh anfra query --lang sql --data-source 'select 1' ``` It fails with the database's own message (wrong host, login refused, unknown database): fix the entry and run it again. The file is read on every command, so there is nothing to restart. ## 4. Model the data Use the [](../anfra-aml/) skill: study the tables with `anfra query --lang sql --data-source ` (schema and a data profile, never data questions), write a model per table in `models/`, their relationships, and a dataset in `datasets/` that bundles them, each with `data_source_name: ''`. ```sh anfra validate # the whole repo; fix every diagnostic anfra show # the datasets, as AQL sees them ``` ## 5. Query it Run one representative AQL query against the dataset with [](../anfra-run-aql/), and check a number against a direct SQL query on the source (a row count, a total). Validation proves the AML is well-formed, not that the numbers are right. ## Then - `anfra serve` serves the repo's Data Apps at `http://127.0.0.1:7878/apps/`: build one with [](../anfra-build-data-app/). - `anfra ingest`, then `anfra search `, finds models, fields and metrics by meaning. - `anfra agent setup` installs these skills into the user's coding agents. - `anfra publish` publishes the repo to the user's org, once they ask. A team that shares work through git publishes what it merged to its shared branch: see [](../anfra-publish/). ## Settings for this machine only `.anfra/config.yml` holds the repo's settings, such as its queries' time zone, and is published with the repo, so the org runs with them too. For a setting only the user's machine should have, such as trying different AQL compiler versions, write it in `.anfra/config.local.yml` instead, with the same keys. It's never committed or published, and `anfra status` lists what it sets. ## Related skills * [](../anfra-aml/) — write the models, relationships and datasets. * [](../anfra-run-aql/) — query a dataset. * [](../anfra-build-data-app/) — build a Data App on the datasets. * [](../anfra-docs/) — look up the anfra and AMQL docs, for what these skills don't cover. * [](../anfra-publish/) — publish to an org, and pull what others published. --- anfra skills 0.23.1