> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need.

# ampctl

`ampctl` is Amp's administration CLI. You use it to register [providers](/providers) and
[datasets](/get-started/concepts/datasets), deploy datasets so Amp extracts and transforms their data, and watch the
[jobs](/managing-amp/jobs) and [workers](/managing-amp/workers) that do it. Each command is a request to the
[Admin API](/managing-amp/admin-api), the HTTP API of Amp's [controller](/running-amp/controller), so a script can do
anything `ampctl` does by calling the Admin API itself.

## Install

[`ampup`](/clis/ampup) installs `ampctl` with `ampd` and `ampsql`, and keeps it at the same version as them. These
pages describe the latest release, v0.0.42, which [`ampup install`](/clis/ampup#ampup-install) installs. Check that
`ampctl` is on your `PATH`:

:::terminal
```bash
ampctl --version
```

```
ampctl v0.0.42
```
:::

To build `ampctl` without `ampup`, see [Installation](/running-amp/installation).

## Connect to Amp

`ampctl` sends its requests to the Admin API at `http://localhost:1610` unless you name another. That's where
[solo mode](/running-amp/solo-mode) and a [controller](/running-amp/controller) with its default configuration listen,
so on the machine that runs Amp, commands work as they are:

:::terminal
```bash
ampctl worker list
```

```
Workers:
  worker (last heartbeat: 2026-10-30T21:01:03.847632+00:00)
```
:::

To administer another Amp, set `AMP_ADMIN_URL` to its Admin API, once for every command in your shell:

```bash
export AMP_ADMIN_URL=http://amp-controller.internal:1610
```

Or pass `--admin-url` to one command, which takes precedence over `AMP_ADMIN_URL`:

```bash
ampctl worker list --admin-url http://amp-controller.internal:1610
```

When nothing answers at that address, the command fails with exit code 1:

```
✗ client error
  → network error connecting to http://localhost:1610/workers
    → error sending request for url (http://localhost:1610/workers)
    → client error (Connect)
    → tcp connect error
    → Connection refused (os error 61)
```

Check that Amp is running, and that the URL and its port match the controller's `admin_api_addr`
([Configuration Reference](/running-amp/configuration-reference)).

## Authentication

Amp doesn't check who sends a request. A deployment that needs to, like a hosted Amp, puts a gateway in front of the
Admin API that checks a token and decides which [namespaces](/get-started/glossary) it can read and write. To use one,
set `AMP_AUTH_TOKEN` to the token you were given, or pass it with `--auth-token`. `ampctl` sends it in each request's
`Authorization: Bearer` header.

```bash
export AMP_AUTH_TOKEN=…
```

Prefer the environment variable: other users of the machine can read a command's flags in its process list.

A namespace your token wasn't granted answers like one that doesn't exist, so a command fails with an error like
`namespace 'acme' not found` whether it exists or not. Solo mode has no gateway: it needs no token, and every namespace
is open.

## Commands

| Command                                      | What it manages                                                                              |
| -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [`ampctl dataset`](/clis/ampctl/dataset)     | Datasets: register and deploy versions, check their status, stop, remove, and restore them.  |
| [`ampctl manifest`](/clis/ampctl/manifest)   | Manifests: generate one for a raw dataset, and store, inspect, and prune the ones Amp keeps. |
| [`ampctl job`](/clis/ampctl/job)             | Jobs, the work that workers run: list, inspect, stop, and remove them.                       |
| [`ampctl worker`](/clis/ampctl/worker)       | Workers: list them and check their heartbeats and versions.                                  |
| [`ampctl provider`](/clis/ampctl/provider)   | Providers, Amp's connections to chains: register, list, inspect, and remove them.            |
| [`ampctl table`](/clis/ampctl/table)         | Table revisions, the sets of files a table's data is stored in.                              |
| [`ampctl configmap`](/clis/ampctl/configmap) | Config maps, configuration documents that Amp stores but doesn't load yet.                   |
| [`ampctl verify`](/clis/ampctl/verify)       | Checks a dataset's extracted data against the chain.                                         |
| [`ampctl trace`](/clis/ampctl/trace)         | Reports on how long queries and jobs took, from Amp's traces.                                |

Each command group also answers to its plural, so `ampctl datasets list` is `ampctl dataset list`. `trace` and `verify`
have no plural.

## Global flags

Every command that calls the Admin API takes these flags:

| Flag                        | Environment variable | Default                 | Description                                                                                |
| --------------------------- | -------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
| `--admin-url <ADMIN_URL>`   | `AMP_ADMIN_URL`      | `http://localhost:1610` | The Admin API to send requests to. See [Connect to Amp](/clis/ampctl#connect-to-amp).                  |
| `--auth-token <AUTH_TOKEN>` | `AMP_AUTH_TOKEN`     | none                    | The token to send, for a gateway that requires one. See [Authentication](/clis/ampctl#authentication). |
| `--json`                    | none                 | off                     | Prints the result as JSON. See [JSON output](/clis/ampctl#json-output).                                |

Put them after the command they apply to, anywhere among its arguments: `ampctl worker list --json`. Before it, they
fail:

```
error: unexpected argument '--json' found

  tip: 'list --json' exists

Usage: ampctl worker <COMMAND>
```

`ampctl trace`, `ampctl verify`, and `ampctl manifest generate` don't call the Admin API, so they take none of them:
[`trace`](/clis/ampctl/trace) reads from Jaeger, [`verify`](/clis/ampctl/verify) from the query server, and
[`manifest generate`](/clis/ampctl/manifest#ampctl-manifest-generate) runs without Amp.

Every command also takes `-h` for a summary of its options and `--help` for the full help, with examples:
`ampctl dataset deploy --help`. `ampctl help dataset` is the same as `ampctl dataset --help`. `ampctl -V` (or
`--version`) prints `ampctl`'s version.

## JSON output

`--json` prints the result as one line of JSON, for scripts and tools like [`jq`](https://jqlang.org). Each command's
page shows its fields, spread over several lines to make them easier to read.

:::terminal
```bash
ampctl worker list --json | jq -r '.workers[].node_id'
```

```
worker
```
:::

`ampctl` prints results to standard output, and everything else to standard error: progress (`→`), success (`✓`),
warnings (`⚠`), errors (`✗`), and logs. So `--json` output stays parseable when a command also prints messages, and
errors aren't JSON: check the exit code instead.

Colors are on when the output is a terminal. Set `NO_COLOR` to any value to turn them off.

## Logging

`ampctl` logs to standard error. `AMP_LOG` sets how much: `error`, `warn`, `info` (the default), `debug`, or `trace`.
At the default level, a command that fails also logs its error, before the `✗` message:

```
2026-10-30T21:01:03.985473Z ERROR run{admin_url=http://localhost:1610/}:get_workers: ampctl::cmd::worker::list: Failed to list workers error=network error connecting to http://localhost:1610/workers error_source=["error sending request for url (http://localhost:1610/workers)", "client error (Connect)", "tcp connect error", "Connection refused (os error 61)"]
✗ client error
  → network error connecting to http://localhost:1610/workers
…
```

To hide the logs and keep only `ampctl`'s messages, use `AMP_LOG=off`. To see the requests a command makes, use
`AMP_LOG=debug`:

:::terminal
```bash
AMP_LOG=debug ampctl worker list
```

```
2026-10-30T21:01:03.992628Z DEBUG run{admin_url=http://localhost:1610/}: ampctl::cmd::worker::list: Retrieving workers from admin API
2026-10-30T21:01:03.992858Z DEBUG run{admin_url=http://localhost:1610/}:get_workers:list: amp_client_admin::workers: Sending GET request to list workers
2026-10-30T21:01:03.993871Z DEBUG run{admin_url=http://localhost:1610/}:get_workers:list: amp_client_admin::workers: Received API response status=200 OK
Workers:
  worker (last heartbeat: 2026-10-30T21:01:03.847632+00:00)
```
:::

`AMP_LOG` only sets the level of Amp's own logs. The libraries it uses log errors only, unless you set `RUST_LOG`, like
`RUST_LOG=reqwest=debug`, which follows the same rules as for [`ampd`](/running-amp/telemetry).

## Exit codes

| Code | Meaning                                                                                                          |
| ---- | ---------------------------------------------------------------------------------------------------------------- |
| `0`  | The command succeeded, or you declined a confirmation prompt.                                                    |
| `1`  | The command failed: Amp returned an error, or `ampctl` couldn't reach it or read a file. A `✗` message says why. |
| `2`  | The command line is invalid: an unknown command or flag, a missing argument, or a value in the wrong format.     |

A command line that's invalid fails before `ampctl` sends anything, with a message that names the problem:

```
error: invalid value '1worker' for '<NODE_ID>': Invalid worker ID '1worker': must start with a letter, got '1'

For more information, try '--help'.
```

## Files in object storage

The commands that read a file, like [`ampctl dataset register`](/clis/ampctl/dataset) and
[`ampctl provider register`](/clis/ampctl/provider), take a local path or an object storage URL: `s3://`, `gs://`,
`az://`, or `file://`. `ampctl` reads the file itself and sends its contents, so it needs access to the bucket, not
Amp. It takes the credentials from its environment, like `ampd` does
([Storage](/running-amp/storage)): `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for S3,
`GOOGLE_APPLICATION_CREDENTIALS` for Google Cloud Storage, and `AZURE_STORAGE_ACCOUNT_NAME` and
`AZURE_STORAGE_ACCOUNT_KEY` for Azure.

```bash
ampctl dataset register acme/eth_mainnet s3://acme-manifests/eth_mainnet.json --tag 1.0.0
```

A file that isn't there fails with exit code 1, and a message that adds a `/` to its URL:

```
✗ manifest file not found: s3://acme-manifests/eth_mainnet.json/
```

On S3, without an access key, `ampctl` first asks the machine it runs on for credentials, like an EC2 instance for its
role. Elsewhere, that fails after a few seconds, with an error that includes
`Error performing PUT http://169.254.169.254/latest/api/token`.

## Environment variables

| Variable                       | Description                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `AMP_ADMIN_URL`                | The Admin API's URL, like `--admin-url`. See [Connect to Amp](/clis/ampctl#connect-to-amp).                |
| `AMP_AUTH_TOKEN`               | The token to send, like `--auth-token`. See [Authentication](/clis/ampctl#authentication).                 |
| `AMP_LOG`                      | How much `ampctl` logs: `error`, `warn`, `info`, `debug`, or `trace`. See [Logging](/clis/ampctl#logging). |
| `RUST_LOG`                     | Log levels for the libraries `ampctl` uses. See [Logging](/clis/ampctl#logging).                           |
| `JAEGER_URL`                   | The Jaeger API that [`ampctl trace`](/clis/ampctl/trace) reads traces from.                    |
| `JAEGER_AUTH`                  | The `user:password` that [`ampctl trace`](/clis/ampctl/trace) signs in to the Jaeger API with. |
| `NO_COLOR`                     | Turns colors off when set.                                                                     |
| `AWS_*`, `GOOGLE_*`, `AZURE_*` | Credentials for [files in object storage](/clis/ampctl#files-in-object-storage).                           |