# CLI Cloud

> Hosted deployment and agent-operations platform for deploying, billing, managing, and inspecting workspace services through browser, CLI, hosted MCP, and public API surfaces.

Use this root file as the public discovery index for agents. It is not an access grant and not a complete route reference. Authenticated live discovery responses define what the current caller can use.

## Start Here

- [CLI Cloud app](https://app.clicloud.co/): Browser entry point for sign-in, API-key issuance, billing, deployments, and service inspection.
- [Agent operating skill](https://app.clicloud.co/skill.md): Procedural operating contract for agents working against CLI Cloud.
- [Agent-readable sitemap](https://app.clicloud.co/sitemap.md): Markdown sitemap for public agent discovery surfaces.
- Authenticated capabilities: GET or POST https://app.clicloud.co/backend/api/public/capabilities - Session-bound live capability readback for the current workspace.
- Bootstrap: POST https://app.clicloud.co/backend/api/public/bootstrap - Authenticated workspace and session bootstrap.
- Connect config: GET or POST https://app.clicloud.co/backend/api/public/connect-config - Hosted MCP, CLI, and API-key connection metadata after authentication.
- Task recipes: GET or POST https://app.clicloud.co/backend/api/public/agent/task-recipes/list - Browsable workflow starters, blockers, next steps, and agent task guidance.
- [Agent Spaces OpenAPI](https://app.clicloud.co/backend/api/public/openapi/agent-spaces.json): OpenAPI 3.1 contract for public Agent Space lifecycle operations.
- [Deployment Jobs OpenAPI](https://app.clicloud.co/backend/api/public/openapi/deployment-jobs.json): OpenAPI 3.1 contract for deployment-job create, replay, cancellation, list, status, and bounded-log readback.
- [Billing Trust OpenAPI](https://app.clicloud.co/backend/api/public/openapi/billing-trust.json): OpenAPI 3.1 contract for non-metered workspace credit balance and bounded recent billing activity.
- [Billing Checkout OpenAPI](https://app.clicloud.co/backend/api/public/openapi/billing-checkout.json): OpenAPI 3.1 contract for preparing a platform-owned hosted credit checkout with billing.manage.
- [Service Lifecycle OpenAPI](https://app.clicloud.co/backend/api/public/openapi/service-lifecycle.json): OpenAPI 3.1 contract for service restart, suspend, resume, delete, and durable operation-status readback.
- [Serverless Invocations OpenAPI](https://app.clicloud.co/backend/api/public/openapi/serverless-invocations.json): OpenAPI 3.1 contract for the complete public serverless endpoint and invocation lifecycle.

## Fast Path

- Install the organization-owned CLI with `npm install --global @clicloud/cli`.
- For application code or remote-agent automation, install the typed client with `npm install @clicloud/sdk`.
- Run `clicloud login`.
- Run `clicloud whoami` to confirm the active workspace.
- Run `clicloud connect` when the next step is Claude Code, Cursor, or VS Code setup.
- One rule: log in once, let local CLI/MCP reuse that saved login, and issue a key only for hosted MCP, direct API, or headless work.
- Then use bootstrap, connect config, and task recipes to choose the right deploy, billing, or service workflow.

## Agent Surfaces

- CLI: install `@clicloud/cli`, run `clicloud login`, then `clicloud connect` for Claude/Cursor/VS Code setup, and reuse the saved workspace credential.
- SDK: install `@clicloud/sdk` for the importable typed client; it shares CLI Cloud public contracts and does not install another executable.
- Hosted MCP: use the MCP URL and auth mode returned by connect config.
- Public API: use `https://app.clicloud.co/backend` plus `/api/public/...` routes; prefer the saved workspace API key, and reuse an already-approved browser session only when the workflow is already running in the browser surface.
- Humans and agents share the same workspace access; login, session reuse, and imported API keys are just different transports for that one identity plane.
- Preferred auth: run `clicloud login`; a human approves the browser/device prompt once, then CLI, MCP, and API flows reuse the same saved workspace credential.
- Headless or CI fallback: start with one `Deploy` key in Settings -> API Keys, import it with `clicloud login --token <api-key> [--workspace <workspace-slug>]`, and use it as `Authorization: Bearer <api-key>` for API calls. Use broader scopes only for billing, API-key lifecycle, or admin review.
- After auth: run `clicloud connect` for local client setup when needed, then call bootstrap and follow returned `nextActions` before opening new work loops.
- Stable workflow starters: use connect config `taskRecipes` for setup and common task entry points.

## Core Workflows

- Auth: `clicloud login`, `clicloud connect`, `clicloud whoami`, `clicloud auth status`, and `clicloud logout`.
- API keys: issue, list, rotate, and revoke scoped workspace keys.
- Billing: balance, activity, governance, payment status, quote, top-up, and settlement reconciliation.
- Deployments: Git repositories, archives, registry images, catalog templates (list/show/deploy), Helm charts, workload manifests, one-off deployment jobs, readiness, service readback, logs, stats, exec, billing posture, and cleanup.
- Agent Spaces: create, list, inspect, start, stop, rebuild, delete, foreground exec, and durable runs; direct API consumers can discover lifecycle schemas from the scoped OpenAPI document.
- Services: list, get, env apply, scale, resource controls, billing controls, restart, suspend, resume, delete, domains, and topology.
- Guest deploy: create a bounded guest deployment, claim it into a workspace, or destroy it.
- Feedback: submit bugs, support tickets, and agent evidence with JSONL through POST `/backend/api/public/feedback` for browser sessions or POST `/backend/api/feedback` for CLI, MCP, and API-key flows.
- Endpoint invocation: configured API endpoints and AI workers can be invoked through readback URLs; prefer `https://functions.clicloud.co/<workspace>/<endpoint>` when endpoint readback exposes it. Do not describe this as deployable user-authored functions, scheduled jobs, cron, or webhook trigger authoring unless live capability readback exposes those features.

## Public Boundaries

- Use only platform-owned domains in public output.
- Do not expose provider hosts, provider API keys, internal runtime refs, cluster internals, pod ids, provider endpoint ids, filesystem paths, or platform secrets.
- Treat live capability readback, connect config, and route responses as authoritative over this index.
- Preserve public `errorId`, `correlationId`, and `requestId` values for support without exposing internal diagnostics.
- Prefer CLI or MCP for agent operation when available; use raw HTTP for direct integration only.

## Optional

- [Client LLM gateway](https://app.clicloud.co/llm/v1): OpenAI-compatible client gateway. Use only client gateway keys for model requests.