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

# Client

> Programmatic access to deployed Capsule apps with `cpsl.Client`.

`cpsl.Client` is the lightweight Python client for talking to deployed Capsule apps from outside the app runtime.

You will usually reach for it when the app already exists and you want to talk to it from somewhere else, such as a smoke test, admin script, or another Python service.

It is useful for:

* deploy smoke tests
* scripts and admin tools
* cron jobs
* other Python services that want to call a Capsule app

## Worked example

The most common use is a deploy smoke test for a real app:

```python theme={null}
import cpsl

client = cpsl.Client()

first = client.chat(
    "support-ops",
    "How many threads are waiting for review right now?",
)
second = client.chat(
    "support-ops",
    "Turn that into a two-step triage plan.",
    session_id=first.session_id,
)

assert first.text.strip()
assert second.text.strip()
assert first.session_id == second.session_id
```

That pattern is useful because it exercises both the app's answer quality and its session continuity after a deploy.

## Setup

The client authenticates from `capsule login` by default:

```python theme={null}
import cpsl

client = cpsl.Client()
```

You can also pass a token manually:

```python theme={null}
client = cpsl.Client(token="...")
```

If you have already run `capsule login`, the zero-argument form is usually all you need.

## App lookup methods

| Method                                | Purpose                    |
| ------------------------------------- | -------------------------- |
| `list_apps()`                         | List apps in the workspace |
| `get_app(name_or_id)`                 | Get metadata for one app   |
| `create_checkout(app, return_url="")` | Create a checkout URL      |
| `list_payments(app)`                  | List payments for an app   |
| `get_earnings(app)`                   | Get earnings summary       |

## Chat methods

### `chat(app, text, session_id=None)`

Send a message and wait for the full response.

```python theme={null}
reply = client.chat("support-ops", "How many support threads are waiting for review right now?")
print(reply.text)
```

If you are writing a quick post-deploy smoke test, this is usually the most convenient entry point.

Returns `ChatResponse` with:

* `text`
* `session_id`
* `request_id`
* `raw`

### `stream(app, text, session_id=None)`

Stream a response via SSE:

```python theme={null}
for chunk in client.stream("support-ops", "Summarize the riskiest support threads."):
    print(chunk.text, end="")
```

This is handy when you want your script to show progress instead of waiting for the entire response.

Each `StreamChunk` exposes:

* `event`
* `data`
* `text` convenience property
* `done` convenience property

## Session continuity

Pass `session_id` if you want multiple client calls to continue the same conversation:

```python theme={null}
first = client.chat(
    "support-ops",
    "How many threads are waiting for review, and which queue looks busiest?",
)
second = client.chat(
    "support-ops",
    "Turn that into a two-step triage plan.",
    session_id=first.session_id,
)
```

Without `session_id`, each call starts a fresh conversation.

## Typical use

Example smoke test:

```python theme={null}
import cpsl

client = cpsl.Client()
reply = client.chat("support-ops", "Give me a one-sentence triage plan for the current support queue.")

assert reply.text.strip()
assert reply.session_id
print("smoke test passed")
```

## See also

* [Deploy An App](/build/deploy-an-app)
* [CLI Reference](/reference/cli)