# Use the CLI

Install the origin CLI, log in through your browser or with a device code, manage your session and profile, and read the CLI's JSON output and exit codes.

The `origin` CLI lets you manage Origin Cloud from a terminal. Install it, log in once, and every command runs as you until your session expires.

## Before you begin [#before-you-begin]

<BeforeYouBegin>

- An Origin Cloud user account. You create one at [console.origincloud.eu](https://console.origincloud.eu); see [Create your account](/docs/platform/getting-started#step-0-create-your-account).
- A Linux or macOS machine with an x86-64 or ARM64 processor. The CLI isn’t built for Windows.

</BeforeYouBegin>

<Callout type="tip">

On Windows, you can run the Linux build of the CLI under WSL (Windows Subsystem for Linux). Install it inside your WSL distribution with the install script below.

</Callout>

## Install the CLI [#install-the-cli]

The CLI is published at packages.origincloud.eu as one binary per platform, with a `SHA256SUMS` file and a GPG signature over it.

| Binary | Platform |
| --- | --- |
| `origin-linux-amd64` | Linux, x86-64 |
| `origin-linux-arm64` | Linux, ARM64 |
| `origin-darwin-arm64` | macOS, Apple silicon |
| `origin-darwin-amd64` | macOS, Intel |

The Linux builds are statically linked and run on any distribution.

### Install with the install script [#install-with-the-install-script]

1. Run the install script. It picks the binary for your machine, verifies it against `SHA256SUMS`, and installs it to `~/.local/bin`:

   ```sh
   curl -fsSL https://packages.origincloud.eu/install.sh | sh
   ```

   The script installs nothing if the checksum doesn’t match, or if your machine has neither `sha256sum` nor `shasum` to check it with.

1. If the script reports that `~/.local/bin` isn’t on your `PATH`, add it:

   ```sh
   export PATH="$HOME/.local/bin:$PATH"
   ```

1. Verify the installation:

   ```sh
   origin --version
   ```

The script reads these environment variables:

| Variable | Default | Effect |
| --- | --- | --- |
| `ORIGIN_VERSION` | The latest stable version | Install a specific version, for example `v1.9.15`. |
| `ORIGIN_INSTALL_DIR` | `~/.local/bin` | Install the binary into this directory. |
| `ORIGIN_BASE_URL` | `https://packages.origincloud.eu` | Download from a mirror with the same layout. The checksum is still verified. |

For example, to install a specific version:

```sh
curl -fsSL https://packages.origincloud.eu/install.sh | ORIGIN_VERSION=v1.9.15 sh
```

### Install manually [#install-manually]

Each version lives under `https://packages.origincloud.eu/cli/<version>/`, and `https://packages.origincloud.eu/cli/latest` names the latest stable version.

1. Download the binary for your platform, the checksum file and its signature. For Linux on x86-64:

   ```sh
   version="$(curl -fsSL https://packages.origincloud.eu/cli/latest)"
   base="https://packages.origincloud.eu/cli/${version}"
   curl -fsSLO "$base/origin-linux-amd64"
   curl -fsSLO "$base/SHA256SUMS"
   curl -fsSLO "$base/SHA256SUMS.asc"
   ```

1. Optional: verify the signature on `SHA256SUMS` with the Origin Cloud release key:

   ```sh
   curl -fsSL https://packages.origincloud.eu/origincloud-release.asc | gpg --import
   gpg --verify SHA256SUMS.asc SHA256SUMS
   ```

   `gpg` reports `Good signature from Origin Cloud Release <release@origincloud.eu>`. Check that the key’s fingerprint is exactly:

   ```text
   FEE6 FD74 A88C 5DB8 959F  5A1B 0BE6 AF84 2E0B 034A
   ```

   A different fingerprint means the key didn’t come from Origin Cloud. Don’t install the binary.

1. Verify the binary against the checksum file. On macOS, use `shasum -a 256 --check` instead of `sha256sum --check`.

   ```sh
   sha256sum --check --ignore-missing SHA256SUMS
   ```

1. Make the binary executable and put it on your `PATH`:

   ```sh
   chmod +x origin-linux-amd64
   mkdir -p ~/.local/bin
   mv origin-linux-amd64 ~/.local/bin/origin
   ```

1. Verify the installation:

   ```sh
   origin --version
   ```

Released versions never change: the files under a version’s directory are the same every time you download them.

## Log in [#log-in]

`origin id login` opens the Origin Cloud login page in your browser and waits for you to log in there. The CLI never sees your password. Whatever the login page offers works, including a second factor.

1. Run the login command:

   ```sh
   origin id login
   ```

   If no browser opens, the CLI prints the address to open yourself.

1. Log in on the page that opens. The CLI waits up to five minutes, then stops with an error.
1. Verify that you’re logged in. The CLI prints who you are when the login finishes, and this command shows your user:

   ```sh
   origin iam current-user
   ```

### Log in without a browser [#log-in-without-a-browser]

On a machine without a browser, such as a server you reached over SSH, use a device code instead.

1. Run the login command with `--device`:

   ```sh
   origin id login --device
   ```

   The CLI prints an address, a short code, and how many minutes the code stays valid.

1. Open the address on any other device, such as your laptop or phone. Check that the page shows the same code, then log in and approve the request.
1. The CLI finishes on its own once you approve. It fails if you deny the request or the code expires first.

## How sessions work [#how-sessions-work]

A login stores a session for your local user account. The CLI renews the session’s access token automatically whenever it has expired. When the session itself expires, commands fail with `authentication: not authenticated`, and you run `origin id login` again.

The session is stored in `~/.local/share/origincloud/`, or under `$XDG_DATA_HOME/origincloud/` if you set that variable. Treat the directory like a password: anyone who can read it can act as you until the session expires.

There’s no logout command. To end the session on a machine, delete the session directory:

```sh
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/origincloud"
```

The next command then fails as unauthenticated until you run `origin id login` again.

For scripts and CI jobs, which can’t log in interactively, use a service account instead. See [Service accounts](/docs/iam/service-accounts).

## Use your access token outside the CLI [#use-your-access-token-outside-the-cli]

`origin id token` prints the current access token, renewing it first if it has expired. Without a valid session, it fails with `unauthenticated`. Use it to call the GraphQL API with your own tools.

| Command | Prints |
| --- | --- |
| `origin id token` | `{"token": "<token>"}` |
| `origin id token --raw` | The bare token |
| `origin id token --as-header` | `{"Authorization": "Bearer <token>"}` |
| `origin id token --as-header --raw` | `Authorization: Bearer <token>` |

For example, to send an API request with `curl`:

```sh
curl -sS https://api.origincloud.eu/graphql \
  -H "$(origin id token --as-header --raw)" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ admin { organisations { orgId name status } } }"}'
```

## Set profile values [#set-profile-values]

The profile holds local defaults for the CLI. `origin config profile` shows it, and `origin config profile-set <key> <value>` changes one value.

| Key | Effect |
| --- | --- |
| `default-username` | Pre-fills the username on the browser login page. You can still change it there. |
| `output-format` | The output format. `json` is the only value. |

For example:

```sh
origin config profile-set default-username jane@example.com
```

The profile is stored in `~/.config/origincloud/`, or under `$XDG_CONFIG_HOME/origincloud/` if you set that variable.

## Read the output [#read-the-output]

Every command prints JSON on standard output. Login prompts and messages go to standard error, so you can pipe the output into a tool such as `jq`.

- On success, a command exits with `0` and prints the data the API returned.
- On failure, it exits with `1` and prints a failure envelope. The `description` carries the API’s message, its error code in parentheses and the correlation id:

  ```json
  {
    "code": "failure",
    "description": "invalid input on field quota: organisation quota exceeded: ... (BAD_REQUEST) [correlation: 4bf92f3577b34da6a3ce929d0e0e4736]"
  }
  ```

The `code` in the envelope is always `failure`. For what the API error code means, see [Error codes](/docs/platform/reference/errors).

## Global options [#global-options]

These options go before the command group, for example `origin --api <url> compute list-instances ...`.

| Option | Effect |
| --- | --- |
| `-a`, `--api <URL>` | Sends requests to a different GraphQL endpoint. The default is `https://api.origincloud.eu/graphql`. Login always uses the Origin Cloud login page. |
| `-c`, `--config <FILE>` | Accepted, but doesn’t change which profile the CLI reads. |
| `-d`, `--debug` | Accepted, but doesn’t change the output. |
| `-V`, `--version` | Prints the CLI version. `origin version` prints it as JSON. |
| `-h`, `--help` | Prints help for the CLI, a command group or a command. |

For every command and its options, see the CLI reference of each guide, starting with [Platform CLI commands](/docs/platform/reference/cli).

## Related [#related]

- [Use the GraphQL API](/docs/platform/access/api)
- [Platform CLI commands](/docs/platform/reference/cli)
- [`origin compute` commands](/docs/compute/reference/cli)
- [`origin storage` commands](/docs/storage/reference/cli)
- [`origin network` commands](/docs/network/reference/cli)
- [`origin iam` commands](/docs/iam/reference/cli)