---
title: "Sine Cloud CLI"
description: "Authenticate with device login, discover Agents, Box, Powers and Gateway resources, call every published operation, and recover uncertain writes with the first-party sinecloud CLI."
image: "https://docs.sinecloud.dev/opengraph.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sinecloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sine Cloud CLI

`sinecloud` is the first-party command-line client for the same customer APIs. It authenticates with an organization API key created by device login, never asks you to paste a key into the terminal, and derives its commands from the published OpenAPI documents.

## Install and sign in

The CLI is a Node package in this repository until a public distribution channel is announced:

```bash
pnpm cli:build
node apps/cli/dist/cli.mjs auth login
```

`auth login` prints an approval URL and a short code. Approve it in the browser, choose an organization, and the CLI saves a minimal-scope key to `$XDG_CONFIG_HOME/sinecloud/config.json` (directory `0700`, file `0600`). Session tokens are used only during login and are never saved.

## Discover resources

```bash
sinecloud agents list --json                 # Agents instances visible to this key
sinecloud box list --json                    # Box resources in the organization or project
sinecloud powers catalog list --json
sinecloud gateway models list --json
```

Use a returned ID with the generated command for that operation:

```bash
sinecloud agents capabilities list --instance INSTANCE_ID --json
sinecloud agents sessions list --instance INSTANCE_ID --json
sinecloud box workspace files list --box-id BOX_ID --path /workspace --json
sinecloud box executions create --box-id BOX_ID \
  --body '{"executionId":"<uuid>","command":"pwd","cwd":"/workspace","timeoutMs":10000}' --wait --yes
```

## Powers quotes and BYOK

```bash
sinecloud powers endpoints quote --endpoint-id ENDPOINT_ID --json > quote.json
sinecloud powers runs create --quote quote.json \
  --body '{"endpointId":"ENDPOINT_ID","input":{}}' --yes
```

`--quote` pins both the endpoint revision and the quoted price version. If the price changes, the server returns `409 priceChanged` without dispatching; read the quote again and start a new run. Omit `--connection-id` for platform execution, or pass your own connection ID for organization BYOK.

BYOK credentials are read from standard input, never from arguments:

```bash
printf '%s' '{"apiKey":"…"}' | sinecloud powers connections replace \
  --connection-id CONNECTION_ID \
  --body '{"providerId":"…","authProfileId":"…","authType":"api_key"}' \
  --credentials-stdin --yes
```

## Recovery, limits and exit codes

Mutating calls record their identity locally before dispatch. An unknown outcome exits `9` and prints a `--resume <id>` instruction; resend the exact same body to reuse the original identity. Do not retry a non-idempotent request with a new key.

Local preflight limits: Agents 256 KiB, Powers 64 KiB, Box command 1 MiB, Box file write 16 MiB, Gateway 1 MiB. Paid operations ask for confirmation on a TTY and require `--yes` otherwise.

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 2 | Usage error |
| 3 | Authentication failed |
| 4 | Permission, scope or project denied |
| 5 | Not found |
| 6 | Conflict or changed price/revision |
| 7 | Rate limited |
| 8 | Not admitted |
| 9 | Unknown outcome; recover with `--resume` |
| 10 | Read failed or upstream unavailable |

Source: https://docs.sinecloud.dev/cli/index.mdx