Metadata-Version: 2.4
Name: socaity-cli
Version: 0.1.13
Summary: Socaity platform CLI: login, catalog browsing, run, and APIPod deployment commands.
Author: SocAIty
License: MIT
Project-URL: Repository, https://github.com/SocAIty/socaity-cli
Project-URL: Homepage, https://www.socaity.ai
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx2>=2.9
Requires-Dist: socaity-schemas>=0.1.10
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# socaity-cli

The command line for the [socaity.ai](https://www.socaity.ai) platform: login, catalog browsing,
`socaity run`, and APIPod deployment tooling. One `socaity` command, shared by the
[socaity SDK](https://github.com/SocAIty/socaity) and [APIPod](https://github.com/SocAIty/apipod).

The package is deliberately small: `httpx2` and `socaity-schemas` are the only dependencies.
Commands that need more (SDK run, container builds) delegate to the `socaity` or
`apipod` package and tell you what to install when it is missing.

## Install

```bash
pip install socaity-cli
```

You get `socaity-cli` as part of `pip install socaity` or `pip install apipod` as well.

## Commands

| Command | Needs | What it does |
|---------|-------|--------------|
| `socaity login` / `logout` / `whoami` | - | Browser login, credentials in `~/.config/socaity/` |
| `socaity list services\|models` | - | Browse the AI catalog |
| `socaity search "flux schnel"` | - | Typo-tolerant search (`--collections services,models,jobs`) |
| `socaity jobs [job_id]` | login | List/search jobs; `--q`, `--expand data,files,billing,social`, `--visibility` |
| `socaity projects [project_id]` | login | Your projects; `--expand jobs` embeds member jobs |
| `socaity run <target>` | `socaity` | Catalog job, agent turn, or workflow run |
| `socaity connector add <url>` | login | Register an HTTP API (OpenAPI URL, docs page or API root) or MCP server as a private connector; `--token-env NAME` or `--oauth` |
| `socaity connector auth <service_id>` | login | Change the connector's credential: `--token-env NAME` or `--oauth` (prints and opens the authorize URL) |
| `socaity connector disconnect <service_id>` | login | Remove your credential binding; connector and vault row stay |
| `socaity scan` | `apipod` | Scan a project and generate `apipod.json` |
| `socaity build [file]` | `apipod` | Build the deployment container |
| `socaity start [entrypoint]` | `apipod` | Run an APIPod service locally |
| `socaity deploy [target]` | `apipod` | Deploy to Socaity (wraps `apipod deploy`) |

Use `--project-dir DIR` with scan/build/start/deploy to point at a service project directory
(e.g. `socaity --project-dir simple_test_service deploy serverless-runpod --yes`).

## Configuration

| Env var | Default | Purpose |
|---------|---------|---------|
| `SOCAITY_API_KEY` | from login | API key (wins over stored credentials) |
| `SOCAITY_BACKEND_URL` | `https://webapi.socaity.ai` | Platform API (env wins; login file is fallback only, never written into the process) |
| `SOCAITY_FRONTEND_URL` | `https://socaity.ai` | Web UI for browser login |

## Using it as a library

`socaity` and `apipod` build on the same primitives this package exposes:

```python
from socaity_cli import SocaityBackendClient, get_api_key, requires
```

`SocaityBackendClient` covers catalog reads, search, and connectors
(`inspect_connector`, `register_connector`, `change_connector_credential`, `disconnect_connector_credential`).
The first three stream server-sent events to `on_event` (`progress`, `authorize`); inspect writes no catalog row.
Catalog rows are `Service` models:
`details[]` holds the spec plus a nested `deployment` or `connector` for the
URL. `details[0]` is the binding unpinned calls use. Pass it as
`details_id` to pin the spec. Resume a deploy with `deployment_id` (that
binding's `deployment.id`).
Connectors are services with `kind == "connector"`.
`requires("apipod")` guards a function behind an optional package with a friendly
install hint instead of an ImportError traceback.
