# Installation

## Requirements

| Requirement | Version / Notes |
|  --- | --- |
| Operating system | Windows 10+, macOS 12+, Linux (any modern distro) |


For Node.js functions, you also need Node.js 20+. For C# functions, you need .NET 9 SDK or later.

## Install the Sinch CLI

```bash
npm install -g @sinch/cli
```

Install takes a few seconds. npm automatically selects the right native binary for your platform — no install scripts run, so `npm install --ignore-scripts` works fine.

Do **not** use `--omit=optional`. The CLI binary ships as an optional dependency; if it is skipped the CLI prints an actionable error telling you how to fix it.

If you don't already have Node.js, install [Node.js 20+](https://nodejs.org/) first — npm comes with it.

Verify:

```bash
sinch --version
```

## Authenticate

```bash
sinch auth login
```

Enter your Project ID, Key ID, and Key Secret from the [Sinch Dashboard](https://dashboard.sinch.com) under your project's Access Keys section.

Key secrets are stored in your OS keychain (Windows Credential Manager, macOS Keychain, or Linux Secret Service). Short-lived session tokens are stored in your local config (`~/.sinch/`).

Voice templates run on Voice API v2, which authenticates with the project key pair above. `sinch functions init` runs a Voice service picker for every voice template and writes the picked `VOICE_SERVICE_ID` into the new function's `.env` or `appsettings.json`; you can skip the picker and set the value later. A Voice Application Key and Secret are needed only by the legacy `sinch voice v1` commands, and are supplied with `-a, --app-key` or the `SINCH_APPLICATION_KEY` / `SINCH_APPLICATION_SECRET` environment variables.

## Shell completions

The CLI silently refreshes `~/.sinch/completions.json` on startup. On first run it prints a one-time hint about enabling completions. To install completions into your shell profile:

```bash
sinch completion --install
```

To print the completion script to stdout (e.g. for custom setups):

```bash
sinch completion --shell bash    # Bash
sinch completion --shell zsh     # Zsh
sinch completion --shell powershell  # PowerShell
```

## Updating

```bash
npm install -g @sinch/cli
```

The CLI checks for new versions in the background and prints a notice when one is available. The
check is rate limited to once every 30 minutes and stays quiet in CI, in Docker, when output is
piped, and under `--json` or `--non-interactive`.

### Updating itself

The CLI can also install updates for you. This is **off by default**:

```bash
sinch config set autoUpdate true    # opt in
sinch upgrade                       # check right now, ignoring the rate limit
sinch upgrade --status              # what it knows
sinch config set autoUpdate false   # opt back out
```

When it is on and an update is available, the CLI records what it wants to install, starts a
background helper, and prints one line. Your command then runs and exits **on the version you
started with**. The helper waits for the CLI to exit before installing, so nothing is replaced
underneath a running command, and the new version takes effect on a later run.

It will not update itself in every situation, and says which applies:

| Situation | What happens |
|  --- | --- |
| Not installed with `npm install -g` | Notify only. `npm install -g` would leave a second copy while your PATH kept serving the first |
| The update crosses a minor version (`0.5.x` → `0.6.0`) | Notify only. Before 1.0 the minor is where breaking changes live |
| You are on a `-dev.` build | Notify only. That tag moves on every branch build |
| Automatic installs are paused for a release | Notify only |


If an install does not land cleanly, the helper puts the previous version back rather than leaving
you with a CLI that cannot start.

## Uninstalling

```bash
npm uninstall -g @sinch/cli
sinch auth logout  # remove stored credentials
```