ForjioHuudisIdentityPlugipayPaymentsCatentioAgentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Catentio Docs
⌘K

Installation

Catentio ships two flavors of tooling for talking to the control plane:

  • CLI — catentio-saas on your terminal. Best for one-off operations, scripting, and exploration. Uses Huudis device flow for sign-in.
  • SDKs — libraries in Node.js, Python, and Go. Best for embedding Catentio in another product or wiring up integrations.

The portal itself doesn't need anything installed locally — just a browser.

Note: this page covers the SaaS CLI and SDKs (@forjio/catentio-saas-cli, @forjio/catentio-saas-node, catentio-saas, and the Go module under sdk/go/). The agent runtime CLI — the one that ships to a customer VPS — is a separate package in the catentio repo.

CLI

The CLI is published on npm as @forjio/catentio-saas-cli. Install it globally:

npm install -g @forjio/catentio-saas-cli

Verify the install:

catentio-saas --version

You should see something like catentio-saas/0.x.y. If you get command not found, your global npm bin directory isn't on your PATH.

The next step is signing in. The CLI uses Huudis OIDC device flow — no client secret, no copy-pasting tokens:

catentio-saas auth login

The CLI opens a browser tab on huudis.com/device, you confirm the code shown in the terminal, and the CLI stores the session at ~/.catentio-saas/credentials. From then on every command auto-refreshes the access token before it expires.

Prefer not to install globally? You can run it as npx @forjio/catentio-saas-cli <command> for one-off uses, or add it as a dev dependency on a project.

Node.js SDK

The Node SDK is @forjio/catentio-saas-node:

npm install @forjio/catentio-saas-node

It's compatible with Node 20 and later. It ships with TypeScript types out of the box.

There are two ways to authenticate — pick the one that fits your context:

Static API key (server-to-server)

import { CatentioSaasClient } from '@forjio/catentio-saas-node';

const catentio = new CatentioSaasClient({
  apiKey: process.env.CATENTIO_API_KEY,
});

const agents = await catentio.agents.list();
console.log(agents);

API keys are minted in Dashboard → API keys and look like cat_ak_xxxxxxxxxxxxxxxx. They never expire on their own — rotate them when team members leave or you suspect compromise.

Bearer session (device-flow)

If your code is running interactively (a CLI, a script you'll run yourself), use the same device-flow Session the CLI uses:

import { CatentioSaasClient, Session, startDeviceFlow, pollDeviceToken } from '@forjio/catentio-saas-node';

const flow = await startDeviceFlow({ issuer: 'https://huudis.com', clientId: 'catentio-cli' });
console.log('Visit', flow.verificationUriComplete);

const tokens = await pollDeviceToken(flow);
const session = new Session({ ...tokens, issuer: 'https://huudis.com', clientId: 'catentio-cli' });

const catentio = new CatentioSaasClient({ session });

Session handles proactive refresh so long-running processes don't 401 mid-run.

Python SDK

The Python SDK is published on PyPI as catentio-saas:

pip install catentio-saas

It supports Python 3.9+. The import name is catentio_saas (PEP 8 underscore-naming):

from catentio_saas import CatentioClient
import os

with CatentioClient(api_key=os.environ["CATENTIO_API_KEY"]) as catentio:
    agents = catentio.agents.list()
    print(agents)

For device-flow Bearer auth:

from catentio_saas import CatentioClient, Session

session = Session(
    access_token="...",
    refresh_token="...",
    expires_at=1_800_000_000,
    issuer="https://huudis.com",
    client_id="catentio-cli",
)

with CatentioClient(session=session) as catentio:
    runs = catentio.runs.list()

Go SDK

The Go SDK lives in the same repo as Catentio itself:

go get github.com/hachimi-cat/saas-catentio/sdk/go

Import it as catentio:

import catentio "github.com/hachimi-cat/saas-catentio/sdk/go"

Minimal usage:

package main

import (
    "context"
    "fmt"
    "os"

    catentio "github.com/hachimi-cat/saas-catentio/sdk/go"
)

func main() {
    client, err := catentio.NewClient(catentio.ClientOptions{
        APIKey: os.Getenv("CATENTIO_API_KEY"),
    })
    if err != nil {
        panic(err)
    }

    agents, err := client.Agents.List(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Println(agents)
}

It uses only the Go standard library — no external dependencies. Requires Go 1.22+.

Get an API key

For server-to-server use you'll want a static API key:

  1. Sign in to the Catentio portal.
  2. Navigate to Dashboard → API keys.
  3. Click Create API key. Give it a name and a scope.
  4. Copy the secret immediately — we show it once.

The convention across SDKs is to read credentials from environment variables:

Variable Purpose
CATENTIO_API_KEY The full key string — secret, never commit
CATENTIO_BASE_URL Optional — only set if you're pointing at a non-default instance

Don't bake the key into source. Use your environment's secret manager. For local dev, a gitignored .env file is fine. For production, use Vault or your platform's equivalent.

Next