# Zain Ahmed SDKs and CLI

Use the official Zain Ahmed clients to read the public engineering API at https://zainahmed.net. The TypeScript package includes the CLI; the Python package provides synchronous and asynchronous clients; the Go module provides OpenAPI-generated operations and models without third-party runtime dependencies. Public profile, projects, articles, services, and MCP discovery require no API key.

## Official packages

- [TypeScript SDK and CLI: @zainahmed.net/sdk](https://www.npmjs.com/package/@zainahmed.net/sdk)
- [Python SDK: zainahmed-sdk](https://pypi.org/project/zainahmed-sdk/)
- [Go SDK: github.com/thezaynahmed/zainahmed-go](https://pkg.go.dev/github.com/thezaynahmed/zainahmed-go)
- [npm package metadata](https://registry.npmjs.org/@zainahmed.net%2Fsdk/latest)
- [PyPI package metadata](https://pypi.org/pypi/zainahmed-sdk/json)

The npm and PyPI metadata identify https://zainahmed.net as the official homepage. The Go package documentation links to the same domain and is published from the official repository. Check each package reference for versions and runtime requirements before installing.

## CLI quickstart

The executable is `zainahmed`, distributed by `@zainahmed.net/sdk`. Use Node.js 20 or later.

```sh
npx @zainahmed.net/sdk status
npx @zainahmed.net/sdk inspect --endpoint=profile
npx @zainahmed.net/sdk mcp
```

`status` reads the API discovery index. `inspect` retrieves a public resource. `mcp` prints connection configuration; it does not install a server or change your client settings.

## TypeScript quickstart

```sh
npm install @zainahmed.net/sdk
```

```ts
import { ZainAhmedClient } from "@zainahmed.net/sdk"

const client = new ZainAhmedClient()
const profile = await client.profile.get()
console.log(profile.name)
```

Use this in an ES module or another environment that supports top-level await. No token or environment variable is needed for this read.

## Python quickstart

Use Python 3.10 or later in a virtual environment.

```sh
python -m venv .venv
source .venv/bin/activate
python -m pip install zainahmed-sdk
```

```py
from zainahmed import ZainClient

with ZainClient() as client:
    profile = client.get_profile()
    print(profile["name"])
```

The context manager closes the HTTP client. On Windows, activate the environment with `.venv\Scripts\Activate.ps1` instead.

## Go quickstart

Use Go 1.25 or later. In a Go module, install:

```sh
go get github.com/thezaynahmed/zainahmed-go@v0.1.0
```

```go
package main

import (
    "context"
    "fmt"
    "log"

    zainahmed "github.com/thezaynahmed/zainahmed-go"
)

func main() {
    client, err := zainahmed.New(zainahmed.Options{})
    if err != nil { log.Fatal(err) }
    response, err := client.GetProfile(context.Background(), zainahmed.RequestOptions{})
    if err != nil { log.Fatal(err) }
    var profile zainahmed.ProfileResponse
    if err := response.Decode(&profile); err != nil { log.Fatal(err) }
    fmt.Println(profile.Name)
}
```

Run with `go run .`. Every operation accepts a context for cancellation. Response headers expose rate limits, `Retry-After`, and job locations; requests are never automatically retried. See the [Go package reference](https://pkg.go.dev/github.com/thezaynahmed/zainahmed-go) and [source README](https://github.com/thezaynahmed/zainahmed-go) for pagination, sandbox writes, and errors.

## MCP and direct HTTP alternatives

- [Operations MCP](https://zainahmed.net/mcp) and its [operations card](https://zainahmed.net/.well-known/mcp/server-card.json).
- [Documentation MCP](https://zainahmed.net/mcp/docs) and its [documentation card](https://zainahmed.net/.well-known/mcp/docs-server-card.json).
- [MCP setup guide](https://zainahmed.net/docs/mcp).
- [OpenAPI specification](https://zainahmed.net/openapi.json) and [public API discovery](https://zainahmed.net/api/v1).

Discover current MCP tool names and parameter schemas with `tools/list`; the operations and documentation servers have different tool catalogs.

## Safe integration and retries

Start with a public read. To test contact validation without sending an email, use the [zero-mutation sandbox](https://zainahmed.net/sandbox) or `POST /api/v1/sandbox/contact` directly. Do not use a live contact submission as a smoke test.

For a real, user-authorized inquiry, keep the same `Idempotency-Key` and payload across retries. Honor `Retry-After` on HTTP 429. Provider acceptance does not confirm inbox delivery. Contact delivery depends on production configuration, and agent registration/token issuance is currently unavailable. Read the [access contract](https://zainahmed.net/auth.md) before implementing a write workflow.

## Related documentation

- [Zain Ahmed developer portal](https://zainahmed.net/developers)
- [Documentation index](https://zainahmed.net/docs)
- [Machine-readable version of this guide](https://zainahmed.net/docs/sdk.md)
- [Agent instructions](https://zainahmed.net/agents.md)