Quickstart Crew CLI

The smallestai agent-crew CLI is built for rapid iteration. Test your crew locally with a single command, then deploy to the cloud when ready. No configuration files, no Docker, no infrastructure management.

Installation

The CLI comes bundled with the SDK:

$
pip install smallestai

ERROR | Startup validation failed — pod will not accept sessions. ValueError: Session not initialized

Verify the installation:

$
smallestai --help

You’ll need a Smallest API key (from app.smallest.ai/dashboard/api-keys) for the CLI and SDK helpers. Export it:

$
export SMALLEST_API_KEY=sk_...

Plus an LLM for the example below. The Atoms Crews SDK ships an OpenAIClient that accepts any OpenAI-compatible endpoint — pick one:

1
from smallestai.atoms.crew.clients.openai import OpenAIClient
2
import os
3
4
llm = OpenAIClient(
5
    model="electron",
6
    api_key=os.getenv("SMALLEST_API_KEY"),
7
    base_url="https://api.smallest.ai/waves/v1",
8
)

Test connectivity outside a crew

For a one-off sanity check (verify your key works, the endpoint responds), use the standard openai Python SDK — Electron is OpenAI-compatible, so the official client works as a drop-in by overriding base_url:

1
import os
2
from openai import OpenAI
3
4
client = OpenAI(
5
    api_key=os.environ["SMALLEST_API_KEY"],
6
    base_url="https://api.smallest.ai/waves/v1",
7
)
8
9
resp = client.chat.completions.create(
10
    model="electron",
11
    messages=[{"role": "user", "content": "Respond with a one-sentence greeting."}],
12
    max_tokens=50,
13
)
14
print(resp.choices[0].message.content)

Same code works against OpenAI itself by dropping base_url and swapping model to gpt-4o-mini (and using OPENAI_API_KEY). Use this pattern for backend scripts or smoke tests that aren’t inside a crew node.

Create Your First Agent Crew

Before the CLI has anything to connect to, you need a Python file that defines a crew and starts a WebSocket server. Pick one of the two patterns below and pull the example folder straight from the cookbook — the tar command drops a getting_started/ or background_agent/ directory into your cwd, ready to cd into. For local development, no .env is needed — the examples read SMALLEST_API_KEY (and optionally OPENAI_API_KEY) straight from your shell. For cloud deployment, you’ll need a .env file (see the Ship env vars in a .env step further down). Each folder ships a one-line requirements.txt pinning smallestai, which the cloud build also uses when you deploy.

Single-node crew

A minimal, single-node crew that streams chat completions from an LLM and greets the caller on join — copied from the cookbook’s getting_started.

$
curl -sL https://github.com/smallest-inc/cookbook/archive/refs/heads/main.tar.gz \
>
  | tar -xz --strip-components=2 cookbook-main/voice-agents/getting_started
$
cd getting_started
$
pip install -r requirements.txt

server.py is the entry point — it boots an AtomsCrewApp on ws://localhost:8080/ws. assistant.py contains the OutputCrewNode subclass that streams the LLM response; extend it with your own prompt, tools, and logic.

Multi-node crew with background processing

A two-node example from background_agent — a support agent talking to the user, and a sentiment analyzer running silently in parallel that flags frustration and triggers auto-escalation.

$
curl -sL https://github.com/smallest-inc/cookbook/archive/refs/heads/main.tar.gz \
>
  | tar -xz --strip-components=2 cookbook-main/voice-agents/background_agent
$
cd background_agent
$
pip install -r requirements.txt

app.py wires both nodes into a single CrewSession. support_agent.py is the user-facing OutputCrewNode; it can query the sibling sentiment node mid-conversation. sentiment_analyzer.py is a BackgroundCrewNode — it listens to every transcript event, classifies sentiment, and updates state the support agent reads.

Local Development Workflow

The CLI’s best feature is instant local testing. No need to deploy to test changes.

$
python server.py

$
smallestai agent-crew chat

Cloud Deployment

When you’re ready for production, deploy to Smallest AI’s managed infrastructure.

1
from smallestai import SmallestAI
2
3
# Reads SMALLEST_API_KEY from the environment, or pass api_key="sk_..." explicitly.
4
client = SmallestAI()
5
response = client.atoms.agents.create_agent(name="my-test-agent")
6
agent_id = response.data   # the agent id is a string at .data
7
print(agent_id)

$
smallestai auth login

$
echo $SMALLEST_API_KEY | smallestai auth login

$
smallestai agent-crew init

1
agent_id = "<your-agent-id>"

$
cat > .env <<EOF
$
OPENAI_API_KEY=$OPENAI_API_KEY
$
SMALLEST_API_KEY=$SMALLEST_API_KEY
$
EOF

$
smallestai agent-crew deploy --entry-point server.py

$
smallestai agent-crew builds

$
curl -X PATCH "https://api.smallest.ai/atoms/v1/sdk/agents/$AGENT_ID/builds/$BUILD_ID" \
>
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"isLive": true}'

Command Reference

Authentication

Agent Management

Common Options

Build Management

Deployments are not live by default. This gives you a safety buffer.

To promote a build:

1. Run smallestai agent-crew builds
2. Select the desired build
3. Choose Make Live

To roll back:

1. Run smallestai agent-crew builds
2. Select the previous build
3. Choose Make Live

To take down completely:

1. Run smallestai agent-crew builds
2. Select the LIVE build
3. Choose Take Down

Running the CLI in CI / non-interactive environments

A few commands prompt you for input (an agent picker, a build picker, a password field). These only work in a real terminal. The table below shows which commands work non-interactively and how to substitute for the ones that don’t.

Skipping init in CI

init exists to write .smallestai/config.toml with your agent ID. In CI you can write the same file yourself before running deploy:

$
mkdir -p .smallestai
$
cat > .smallestai/config.toml <<EOF
$
agent_id = "$ATOMS_AGENT_ID"
$
EOF

Promoting and rolling back builds in CI

builds calls the same endpoint for both Make Live and Take Down. You can call it directly:

$
# Promote a build (Make Live)
$
curl -X PATCH "https://api.smallest.ai/atoms/v1/sdk/agents/$ATOMS_AGENT_ID/builds/$BUILD_ID" \
>
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"isLive": true}'
$
$
# Roll back (Take Down)
$
curl -X PATCH "https://api.smallest.ai/atoms/v1/sdk/agents/$ATOMS_AGENT_ID/builds/$BUILD_ID" \
>
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"isLive": false}'

The build ID is printed by deploy on success, and is also available from GET /atoms/v1/sdk/agents/{agentId}/builds.

Error handling

When deployed code raises, the SDK auto-records the error on the call (in calllog.errors[], the Events tab, and webhooks) — you don’t need to wire anything up to get this. The deploy command also warns about env vars your code references before zip upload, and the pod’s /ready endpoint blocks traffic until your crew’s __init__ succeeds. See Error Handling for severity semantics, graceful-fallback patterns, and how to emit your own application-level errors.

More examples

The two crews above are the starting points. The Smallest AI cookbook ships ~15 ready-to-run voice-agent examples covering tool calling, call control, multi-language support, knowledge-base grounding, real banking / scheduling / IVR flows, observability, and more — each in its own directory with the same curl-and-run shape.

Need Help?