JSON Output & Scripting

Every 1ctl command accepts --output json (or -o json) to return machine-readable output instead of the default human-readable table. Use this flag in CI pipelines, shell scripts, and any tool that needs to consume 1ctl output programmatically.

---

The global flag

--output / -o is a global flag — it is placed before the subcommand:

1ctl -o json deploy list
1ctl --output json deploy list

Both forms are equivalent. Placing the flag after the subcommand also works in most shells, but positioning it before the subcommand is consistent with the CLI’s global-flag convention.

---

Commands that support JSON output

Command	JSON shape
1ctl deploy list	Array of deployment objects
1ctl deploy get	Single deployment object
1ctl deploy status	Deployment status object
1ctl deploy releases	Array of release objects
1ctl env list	Array of environment variable objects
1ctl secret list	Array of secret group metadata objects (key names only — never values)
1ctl machine list	Array of machine objects
1ctl token list	Array of token metadata objects
1ctl org list	Array of organization objects
1ctl credits balance	Credits balance object
1ctl credits transactions	Array of transaction objects

Commands that perform mutations (deploy, secret create, env create, etc.) print a confirmation summary; they do not have a structured JSON response shape.

---

Common scripting patterns

Extract the app URL after deploy

URL=$(1ctl deploy get --config satusky.toml -o json | jq -r '.url')
echo "App is live at: $URL"

Assert deployment health in CI

STATUS=$(1ctl deploy status --config satusky.toml -o json | jq -r '.status')
if [ "$STATUS" != "running" ]; then
  echo "Deployment is not healthy: $STATUS"
  exit 1
fi

List names of all running deployments

1ctl -o json deploy list | jq -r '.[] | select(.status == "running") | .name'

Summarize all deployments as a name/status table

1ctl -o json deploy list | jq '[.[] | {name, status}]'

Look up a deployment ID by name

DEP_ID=$(1ctl -o json deploy list | jq -r '.[] | select(.name == "my-api") | .id')

Rollback using a looked-up deployment ID

DEP_ID=$(1ctl -o json deploy list | jq -r '.[] | select(.name == "my-api") | .id')
1ctl deploy rollback --deployment-id "$DEP_ID" --version 3 -y

Check credits balance in a script

BALANCE=$(1ctl -o json credits balance | jq -r '.balance')
echo "Remaining credits: $BALANCE"

---

GitHub Actions integration

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1ctl
        run: curl -sSL https://get.satusky.com/install.sh | sh

      - name: Authenticate
        run: 1ctl auth login --token "${{ secrets.SATUSKY_TOKEN }}"

      - name: Deploy and wait
        run: 1ctl deploy --wait

      - name: Assert healthy
        run: |
          STATUS=$(1ctl deploy status -o json | jq -r '.status')
          test "$STATUS" = "running"

The test built-in exits with a non-zero status if the condition is false, which fails the step and the workflow.

---

Notes

secret list never returns values

1ctl secret list -o json returns secret group metadata — group name, deployment association, and key names. Secret values are never included in any API response after the initial create call. Use secret list to verify that a key exists, not to retrieve its value.

ingress list and service list

These commands currently return table output only. To extract a domain or ingress URL programmatically, use deploy get -o json and inspect the url or ingress field.

Exit codes

All 1ctl commands exit 0 on success and non-zero on error, regardless of --output. The JSON flag does not affect exit code behavior. Scripts should check both exit codes and status fields in the response.

Piping with jq

jq is not bundled with 1ctl. It must be installed separately. On Ubuntu/Debian: apt-get install jq. On macOS: brew install jq. In GitHub-hosted runners, jq is pre-installed.