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

# SDKs and CLI

> Pick how to integrate Alguna from code: the TypeScript, Python, Go and Rust SDKs, the alguna CLI, the REST API or the MCP server, with install steps, a first call in each, and the reference page for every library.

Alguna publishes an official client library for TypeScript, Python, Go and Rust, and the `alguna` command-line tool. All five are generated from the same versioned OpenAPI spec as the [API reference](/docs/api-reference/v2/overview), so every endpoint has a method or a command, and they read and write the same objects the dashboard does: customers, products and prices, quotes, subscriptions and their versions, usage, invoices, payments and revenue schedules. Those objects all read from one versioned agreement per customer, which [How Alguna works](/docs/concepts/how-alguna-works) explains. Use this page to choose a client, connect it, and make a first call. The [reference pages](/docs/api-reference/v2/sdks/overview) hold the full method lists and the details of each library.

## Which one

| You are | Use | Why |
| - | - | - |
| Writing application code (provision customers on signup, meter usage, open checkout, read revenue) | An SDK: [TypeScript](/docs/api-reference/v2/sdks/typescript), [Python](/docs/api-reference/v2/sdks/python), [Go](/docs/api-reference/v2/sdks/go) or [Rust](/docs/api-reference/v2/sdks/rust) | Typed requests, responses and errors, with idempotency and retries built in |
| Writing a shell script, a CI job, or a one-off operation from a terminal | The [CLI](/docs/api-reference/v2/sdks/cli) | Each API operation is one command, with JSON or NDJSON output and `--dry-run` |
| Letting an AI assistant or an agent do the work in plain language | The [MCP server](/docs/ai/mcp) | The same operations as tools, under your role's permissions, with confirmation before each call |
| Pointing a coding agent at the integration | [agents.md](/docs/ai/agent-guide) | The whole contract on one page: URLs, auth, versioning, the object model, errors |
| Working in a language without a library | The [REST API](/docs/api-reference/v2/overview) directly | Send `Authorization` and `Alguna-Version` yourself; the SDK pages show what each library adds |

The API key is a secret, so use the libraries and the CLI on a server, in CI, or on your own machine, never in a browser. For a purchase flow in your product's frontend, use [Embedded Checkout](/docs/hosted/embedded-checkout), where your server mints the session and the browser only mounts it.

## Install

Create an API key in the dashboard under **Settings → Connections → Developers → API keys**. Every library and the CLI read it from `ALGUNA_API_KEY` when you do not pass it in code.

```bash TypeScript theme={null}
npm install @alguna/sdk
```

```bash Python theme={null}
pip install alguna
```

```sh Go theme={null}
go get github.com/alguna-io/alguna-go
```

```bash Rust theme={null}
cargo add alguna
cargo add tokio --features macros,rt-multi-thread
```

```sh CLI theme={null}
npm install --global @alguna/cli
alguna login
```

## Connect

Pin the API version you integrate against. The date in `Alguna-Version` is what fixes the request and response shapes, and a later package release keeps sending the date you set. See [Versioning](/docs/api-reference/v2/overview#versioning).

```typescript TypeScript theme={null}
import { Alguna } from "@alguna/sdk";

// Reads the API key from ALGUNA_API_KEY when you do not pass apiKey.
const alguna = new Alguna({
  apiVersion: "2026-04-01", // recommended — pin the version you integrate against
});
```

```python Python theme={null}
from alguna import Alguna

# Reads the API key from ALGUNA_API_KEY when you do not pass api_key.
client = Alguna(
    api_version="2026-04-01",  # recommended: pin the version you integrate against
)
```

```go Go theme={null}
import (
	alguna "github.com/alguna-io/alguna-go"
	"github.com/alguna-io/alguna-go/client"
	"github.com/alguna-io/alguna-go/option"
)

// With no options, the client reads the API key from ALGUNA_API_KEY.
c := client.NewAlguna(
	option.WithAPIVersion("2026-04-01"), // recommended: pin the version you integrate against
)
```

```rust Rust theme={null}
use alguna::prelude::*;
use alguna::ApiClientBuilder;

fn client() -> Result<Alguna, ApiError> {
    // Reads the API key from ALGUNA_API_KEY when you do not call api_key.
    ApiClientBuilder::default()
        .api_version("2026-04-01") // recommended: pin the version you integrate against
        .build()
}
```

```sh CLI theme={null}
# A flag wins over an environment variable, and an environment variable wins over the key saved by login.
export ALGUNA_API_VERSION=2026-04-01
alguna version
```

## A first call

Create a customer. Each reference page continues from here to a product, a subscription, an invoice and a customer portal session.

```typescript TypeScript theme={null}
const customer = await alguna.customers.create({
  name: "Acme Corp",
  currency: "USD",
  contacts: [{ email: "billing@acme.com", is_primary: true }],
});
```

```python Python theme={null}
from alguna import ContactRequest

customer = client.customers.create(
    name="Acme Corp",
    currency="USD",
    contacts=[ContactRequest(email="billing@acme.com", is_primary=True)],
)
```

```go Go theme={null}
ctx := context.Background()

customer, err := c.Customers.Create(ctx, &alguna.CreateCustomerRequest{
	Name:     "Acme Corp",
	Currency: "USD",
	Contacts: []*alguna.ContactRequest{
		{Email: "billing@acme.com", IsPrimary: true},
	},
})
if err != nil {
	return err
}
```

```rust Rust theme={null}
let customer = client
    .customers
    .create(
        &CreateCustomerRequest {
            name: "Acme Corp".to_string(),
            currency: "USD".to_string(),
            ..Default::default()
        },
        None,
    )
    .await?;
```

```sh CLI theme={null}
alguna customers create --name "Acme Corp" --currency USD
alguna customers list --limit 10
```

## What every library does for you

* Sends the `Authorization` and `Alguna-Version` headers on every request.
* Sends an `Idempotency-Key` on every write, yours or a generated one, and reuses it on each retry, so a retried create never duplicates a record. See [Idempotency](/docs/api-reference/v2/idempotency).
* Retries `408`, `429`, `502`, `503` and `504`, a `409` with `Retry-After`, and network failures, twice by default. Never retries a `500`, because the request may have changed data. See [Errors](/docs/api-reference/v2/errors#retrying).
* Raises a typed error for a failed response, carrying the HTTP status and the `X-Request-Id`. Include that id when you report a problem.

## Sandbox first

Every library and the CLI take a base URL. Point it at `https://api.sandbox.alguna.io` with a sandbox API key, run the whole flow there, then switch the URL and the key for production. Sandbox and production are separate environments with separate keys and data. See [Testing and Sandbox](/docs/getting-started/testing). For the CLI, set `ALGUNA_BASE_URL=https://api.sandbox.alguna.io`.

## Reference

> **[TypeScript](/docs/api-reference/v2/sdks/typescript)**
>
> `@alguna/sdk` on npm: client options, the quick start, errors, pagination and webhooks.

> **[Python](/docs/api-reference/v2/sdks/python)**
>
> `alguna` on PyPI: sync and async clients, typed models and errors.

> **[Go](/docs/api-reference/v2/sdks/go)**
>
> `github.com/alguna-io/alguna-go`: options, pointers for optional fields, errors.

> **[Rust](/docs/api-reference/v2/sdks/rust)**
>
> `alguna` on crates.io: the client builder, async calls, errors.

> **[CLI](/docs/api-reference/v2/sdks/cli)**
>
> Log in, run commands, output formats, idempotency, timeouts and exit codes.

> **[SDKs overview](/docs/api-reference/v2/sdks/overview)**
>
> Packages, source repositories, and how package and API versions relate.

> **[MCP server](/docs/ai/mcp)**
>
> Connect Claude, ChatGPT, Cursor or any MCP client to your account.

> **[Developer quick start](/docs/quickstarts/developers)**
>
> From an API key to a metered, invoiced subscription.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.