# Ingestron CLI

Create reviewed data contracts, configure flows and generate native data-engineering
assets from versioned plugins. Use the same project operations from your terminal
or an MCP client.

The CLI is a thin application over [`@ingestron/core`](https://github.com/ingestron/core).
Providers supply platform-specific generators, connectors and standards. Installing
the CLI does not install a platform provider or connect to a cloud account.

Version 0.16.1 uses core 0.12.5. It adds
`connections add`, `connections flow-add`, `contract scaffold` and `contract map`
for reviewable connector/workflow authoring, an editable first contract and
source-to-target ODCS mapping. `connections flow-add --execution <file>` passes
reviewed provider execution settings to core. Use a qualified local provider and
connector release for execution.

## Get started

Use Node 22.12 or newer, Git and pnpm 10.15.0:

```sh
git clone https://github.com/ingestron/cli.git
cd cli
pnpm install --frozen-lockfile
pnpm build
node build/cli/cli/index.js --help
pnpm examples:check
```

The example creates metadata and a draft contract, checks overwrite protection,
and builds SQL with a synthetic plugin. It needs no private repository or cloud
account and removes its temporary files afterwards.

To install this checkout's CLI in your terminal:

```sh
pnpm pack --pack-destination build/release
npm install --global ./build/release/ingestron-0.16.1.tgz
ingestron --version
```

The package name is `ingestron`; its core dependency is the public, exact version
`@ingestron/core@0.12.5`.

Follow the [five-minute quickstart](docs/quickstart.md) for a project you can keep.

## Work with projects and plugins

Commands use resource groups such as `source`, `contract`, `flow`, `config`,
`provider` and `connector`. Installed packages can add their own namespace:

```text
ingestron provider install local
ingestron connector install github
ingestron <namespace> <resource> <verb> --input request.json
```

Installation caches an exact, qualified version without changing project configuration.
Use `github@1.33.0` for an explicit pin, or `connector update github` to check for a newer
qualified release. Browse installed packages with `ingestron plugin browse`. Command help
shows the selected plugin's input schema without executing it.

- [Command reference](docs/commands.md) — implemented groups, options and errors.
- [Plugins](docs/plugins.md) — exact versions, installation, namespaces and a local starter.
- [Builds and ownership](docs/builds.md) — validate, generate, review and regenerate safely.
- [Automation and MCP](docs/automation.md) — JSON output and explicit permissions.
- [Contributing](CONTRIBUTING.md) — tests, package boundaries and releases.

Builds and checks run locally. Cloud login, deployment and remote flow execution
are not implemented. Local execution requires a compatible installed provider and
explicit `runtime prepare` / `run` commands; generated Python runs as your OS user,
not inside the compiler's JavaScript sandbox. See [security](SECURITY.md).

## Licence

Original code is licensed by **Otrera Limited** under [Apache-2.0](LICENSE).
[NOTICE](NOTICE) and [third-party notices](THIRD_PARTY_NOTICES.md) retain attribution
and dependency terms.

### Select an execution profile

An ingestion flow can declare named `executionProfiles`. Select the environment
and profile independently; datasets and contracts stay in the same logical flow.

```sh
ingestron --environment dev check --flow northwind --profile adf
ingestron --environment dev build --flow northwind --profile adf --out build/adf
```

Omit `--profile` to use the flow's default provider. Local runtime preparation and
execution must select the same profile recorded by the build. A native-provider
build generates assets; it does not deploy or run them on the target platform.