CLI and API
Create and manage hosted cores from a terminal or application.
CLI
CLI 0.1.5 is available from npm. Installation and command checks passed on macOS ARM64 and Linux ARM64. Windows has not been checked.
npm install -g @1sc-hq/1sc@0.1.5
1sc --version
1sc --help
1sc auth login --scopes deployments:readOpen the authorization URL shown in the terminal and approve the device.
1sc auth whoami --json
1sc deployments --json
1sc auth status --jsonThis login grants read access to deployment records. It does not grant permission to create, stop, resume, or destroy a core. Check the scopes in whoami before you run another action.
| Option | Value | Purpose |
|---|---|---|
| --scopes | Comma-separated permission names | Requests the permissions for this device login. |
| --json | No value | Prints structured command results. Device login prints progress as separate JSON lines. |
| --api-url | https://www.1sc.dev | Selects the API for the command. This is the production URL. |
End CLI access
1sc auth logoutLogout removes the saved credential from this CLI configuration. It does not revoke the API token on the server. Revoke the token in API tokens to end its access.
- Open API tokens and revoke the token for the device.
Deployment commands
These commands use the permissions of the selected token. A read-only login cannot run the write actions.
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>Check radio settings
Use a running deployment and its current radio package. Put the settings actually configured in your gNB, UE and site in radio-settings.json. Use the package to compare the expected values.
1sc deployments radio-package <deployment-id> --output radio.zip
1sc deployments radio-configuration-check <deployment-id> --input radio-settings.json --jsonReplace every sample value below with your configured value. The downloaded radio-attach-kit.json identifies the deployment endpoints, PLMN, TAC, slice and DNN.
{
"mcc": "208",
"mnc": "93",
"tac": 1,
"sst": 1,
"sd": "010203",
"dnn": "internet",
"amfN2": "core.example.invalid:38412",
"upfN3": "core.example.invalid:2152",
"radioSourceIp": "198.51.100.42"
}| Field | Value | Source |
|---|---|---|
| mcc, mnc | Strings; preserve the digit counts | The PLMN configured in the gNB. |
| tac, sst | Numbers | The gNB TAC and the gNB/UE slice SST. |
| sd | Six hexadecimal digits | The gNB/UE slice SD. |
| dnn | String | The UE DNN. |
| amfN2, upfN3 | Host and port | The AMF N2 destination and UPF N3 endpoint in the radio configuration. |
| radioSourceIp | IPv4 address | The site's public radio egress address. |
For each mismatch, read checks[].correction. The report compares supplied settings with the deployment and returns liveRadioVerified: false. A live radio run needs separate packet evidence.
1sc deployments customer-radio-run-check <deployment-id> --input radio-run-result.json --jsonFor the default lab data network, use the result JSON from your radio kit. For a reported failure, read failureStage and failureReason. Customer-supplied results retain independentlyVerified: false; keep the captures and run evidence with the report.
Create from the CLI
npx @1sc-hq/1sc deploy --agent --cleanup stopAgent 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 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 |
| Update deployment lifetime | PATCH | /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 |
| Read operation status | GET | /api/v1/operations/:id |
Create, update, stop, resume, destroy, and attach responses include an operationId. Read that operation until its state is succeeded or failed. Errors use a stable code and descriptive message. Treat codes as machine-readable and messages as human-readable context.