# Cademí CLI

`cademi` is the command-line tool for the Cademí API v3. It runs every API operation as a command, signs in as an administrator or with a credential alone, forwards events to your local application, and applies declarative configuration to your account.

## What the CLI does

- **Every API operation as a command.** Commands are generated from the API contract: `cademi products list`, `cademi users create`, `cademi operations get <operation_id>`. Each command's `--help` shows the API route, the required permission, and the body fields. See [Commands](https://cademi.dev/cli/commands.md).
- **Two ways to sign in.** Human mode pairs an administrator's OAuth session with a credential, so the audit trail records the administrator. Autonomous mode uses a credential alone, for scripts and CI. Secrets stay in the operating system keychain. See [Authentication](https://cademi.dev/cli/authentication.md).
- **Safe writes.** Every write carries an `Idempotency-Key`, so automatic retries never duplicate an effect. `--if-match` sends a conditional update, and deletes ask for confirmation.
- **Workflows.** `cademi api` sends a request to any endpoint, `cademi listen` streams events and can forward each one to a local endpoint, `cademi config` validates, plans, and applies manifests, `cademi upload` and `cademi download` transfer files, and `cademi sandbox` resets the sandbox and runs test scenarios.

The CLI runs on macOS, Linux, and Windows, on `amd64` and `arm64`.

## Quickstart

1. Install the CLI on macOS or Linux:

```sh
curl -fsSL https://cli.cademi.dev/install.sh | bash
```

On Windows, in PowerShell:

```powershell
irm https://cli.cademi.dev/install.ps1 | iex
```

Open a new terminal afterwards so the updated `PATH` takes effect. See [Installation](https://cademi.dev/cli/installation.md) for options and updates.

2. Sign in:

```sh
cademi auth login
```

The CLI asks for the platform URL (`https://api.cademi.com.br` by default), opens the browser so an administrator can authorize it, and then asks for the secret of a credential linked to that administrator (`ck_live_...` or `ck_test_...`). To sign in with a credential alone, run `cademi auth login --api-key-only`.

3. Make your first calls:

```sh
cademi credentials current
cademi products list --limit 5
```

`cademi credentials current` calls `GET /credentials/current` and shows the credential, its environment, and its mode. `cademi products list` prints a table in a terminal and JSON when you pipe it.

## Getting help

```sh
cademi --help
cademi products --help
cademi products update --help
```

`cademi --help` lists the core commands and the API resources. Each resource command lists its subcommands, and each operation command documents its route, permission, parameters, and body fields.

`cademi commands` lists every command with its API route in one table. `cademi commands --json` also gives the arguments, flags, and permission of each command, for scripts and agents. See [Finding commands](https://cademi.dev/cli/commands.md#finding-commands).

`cademi version` prints the CLI version, the API release it was built for, and the build commit:

```text
cademi 0.1.4 (api 3.4.5, commit f4cdf2e)
```

The CLI works with any 3.x release of the API. `cademi doctor` warns when the server runs a different release than the CLI. If the server is newer, operations added in that release are still available through [`cademi api`](https://cademi.dev/cli/api.md). If the server is older, some commands may call operations the server does not offer yet. See [Versioning and compatibility](https://cademi.dev/api/versioning.md).

## Report a problem

The fastest way to report a bug is `cademi bug`:

```sh
cademi bug
cademi bug --title "Short summary of the problem"
cademi bug --api --endpoint "PATCH /api/v3/products/{product_id}" --request-id 01J8Z3ZQ4H8K2M0T1S9P7YQF5C
```

`cademi bug` opens a new issue at [github.com/minhacademi/developers](https://github.com/minhacademi/developers/issues) in your browser, with the CLI version, the platform, and the settings from [`cademi env`](https://cademi.dev/cli/environment.md#cademi-env) already filled in. The settings never include secrets or local paths. Nothing is sent until you review the issue and submit it in the browser. `--title` sets the issue title. `--print` prints the issue URL instead of opening the browser, and so does the command when its output is not a terminal.

`cademi bug --api` opens the API bug report instead, for a response that contradicts the API documentation. It fills in the API release the CLI was built for, and `--endpoint` and `--request-id` fill in the method and path of the call and its `request_id`. The `request_id` appears in the error the CLI prints and in the `X-Request-Id` response header. `--request-id` also works in the CLI bug report. `--endpoint` without `--api` is a usage error and exits with code 2.

- Bugs in the CLI and feature requests: run `cademi bug`, or open an issue at [github.com/minhacademi/developers](https://github.com/minhacademi/developers/issues) and include the output of `cademi version` and `cademi env`.
- Questions about using the CLI: [Discussions](https://github.com/minhacademi/developers/discussions).
- Security vulnerabilities: report them privately at [github.com/minhacademi/developers/security](https://github.com/minhacademi/developers/security), never in an issue.
- Problems with the API itself: run `cademi bug --api --endpoint "<METHOD> <path>" --request-id <id>`, or see [Report a problem](https://cademi.dev/api/errors.md#report-a-problem) in the API guides.
- Questions about your account, plan, or data: contact Cademí support.

Issues and discussions are public. Never paste an API key, a token, or data about your users.

[CONTRIBUTING.md](https://github.com/minhacademi/developers/blob/main/CONTRIBUTING.md) summarizes where each kind of report goes.

## Next steps

- [Installation](https://cademi.dev/cli/installation.md): install options, updates, release verification, and uninstalling.
- [Authentication](https://cademi.dev/cli/authentication.md): human and autonomous mode, profiles, and where secrets are stored.
- [Commands](https://cademi.dev/cli/commands.md): how operations become commands, request bodies, output, pagination, and asynchronous operations.
- [Events with `cademi listen`](https://cademi.dev/cli/listen.md): receive events on your machine while you develop.
- [CI and automation](https://cademi.dev/cli/ci.md): run the CLI without a terminal.