> ## 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 {
// 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
`@alguna/sdk` on npm: client options, the quick start, errors, pagination and webhooks.
`alguna` on PyPI: sync and async clients, typed models and errors.
`github.com/alguna-io/alguna-go`: options, pointers for optional fields, errors.
`alguna` on crates.io: the client builder, async calls, errors.
Log in, run commands, output formats, idempotency, timeouts and exit codes.
Packages, source repositories, and how package and API versions relate.
Connect Claude, ChatGPT, Cursor or any MCP client to your account.
From an API key to a metered, invoiced subscription.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.