# CLI and API

Create and manage hosted cores from a terminal or application.

Product: Hosted Core

Human documentation: https://www.1sc.dev/docs/cli-api

Documentation index: https://www.1sc.dev/llms.txt

## CLI

```text
npm install -g @1sc-hq/1sc
1sc auth login
```

Open the authorization URL shown in the terminal and approve the device.

```text
1sc deployments
1sc deployments show <deployment-id>
1sc deployments logs <deployment-id>
1sc deployments events <deployment-id>
1sc deployments stop <deployment-id>
1sc deployments destroy <deployment-id>
1sc deployments resume <deployment-id>
1sc attach run <deployment-id>
1sc verify <deployment-id>
```

> **Billable actions:** Creating, resuming, and validating deployments can start or use billable infrastructure. The CLI prompts for confirmation before mutating actions.

## Create from the CLI

```text
npx @1sc-hq/1sc deploy --agent --cleanup stop
```

Agent mode generates a name, confirms the billable action, emits NDJSON progress, waits for readiness, and verifies hosted attach.

| Option | Required | Default / options | Purpose |
| --- | --- | --- | --- |
| --name <name> | Required unless --agent is set | Any deployment name | Names the deployment. |
| --agent | Optional | Flag | Enables JSON output, --yes, wait, hosted attach verification, and generated naming defaults. |
| --radio-source <cidr\|auto> | Optional | CIDR or auto | Restricts N2/N3 access to the radio source. auto detects the caller's IPv4 /32. |
| --core <fivegc\|free5gc\|open5gs> | Optional | fivegc, free5gc, open5gs; default fivegc | Selects the hosted core implementation. |
| --verify | Optional | Flag | Waits for readiness, then runs hosted attach verification. |
| --cleanup <keep\|stop\|destroy> | Optional | keep, stop, destroy; default keep | Keeps, stops, or destroys the deployment after verification. |
| --timeout <duration> | Optional | Example: 45m; default 30m | Sets the maximum wait time for readiness, attach verification, and cleanup. |
| --yes | Required unless --agent is set | Flag | Confirms the billable deployment action. |
| --api-url <url> | Optional | URL | Overrides the 1sc API URL. |
| --json | Optional | Flag | Prints JSON output. |

## API authentication

- [Create an API token](https://www.1sc.dev/dashboard/agent-access) with the required access bundle, then send it as a Bearer token in the Authorization header.

## What you can automate

| Task | Method | Path |
| --- | --- | --- |
| List deployments | GET | /api/v1/deployments |
| Create a deployment | POST | /api/v1/deployments |
| Read deployment details | GET | /api/v1/deployments/:id |
| Read job events | GET | /api/v1/deployments/:id/events |
| Read logs | GET | /api/v1/deployments/:id/logs |
| Stop the core | POST | /api/v1/deployments/:id/stop |
| Resume the core | POST | /api/v1/deployments/:id/resume |
| Run hosted attach validation | POST | /api/v1/deployments/:id/attach-tests |

Errors use a stable code and descriptive message. Treat codes as machine-readable and messages as human-readable context.