# 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 API URL (`https://api.cademi.com.br` by default) and opens the browser. Enter your account's address, sign in as an administrator with two-factor authentication, and choose Authorize. Back in the terminal, paste the secret of a credential linked to that administrator (`ck_live_...` or `ck_test_...`). To skip the address question in the browser, pass the address with `--platform`, as in `cademi auth login --platform acme.cademi.com.br`. 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.8 (api 3.4.7, commit 7161794)
```

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 operating system and architecture, and the settings from [`cademi env`](https://cademi.dev/cli/environment.md#cademi-env) already filled in. The settings never include secrets, local paths, the profile name, the credential, or your account's address. 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.