For developers · about 25 min

Automate package creation with the CLI and REST API

Create a scoped API client, configure the ripton command-line client without putting secrets in shell history, create a package from a script, and check transfers and jobs from the terminal.

You end up with
A service principal with only the scopes it needs, a working CLI, and a script that creates packages and can be wired to a webhook for completion.
Plan
REST API and CLI are available from the Professional plan, per the pricing page.
Updated

Before you start

  • An administrator to create the API client, and a developer machine with the ripton CLI from your release archive.
  • Your workspace URL, written as https://ripton.example.com in the commands below.
  • A secret manager or environment-variable mechanism for the credential. The CLI deliberately has no secret flags because process arguments and shell history are visible to other users.

Steps

  1. Create an API client

    Admin · API clients

    Open Admin, then API clients, and create a client of type Service. Give it a name that says what it is for, for example 'nightly-export'.

  2. Grant only the scopes you need

    For creating packages and reading their state, choose Transfers write and Transfers read. Avoid All access. The backend enforces role, scope, ownership and resource grants; the CLI never elevates a credential.

  3. Store the credential

    Copy the secret into your secret manager the moment it is shown. Plan to rotate it and revoke it when the automation is retired.

  4. Configure the CLI

    Terminal

    Export the server URL and access token as environment variables, then run a read-only command to confirm access.

  5. Create a package from a script

    Call the packages endpoint with a title, recipients and optional expiry. The response includes the package ID; keep it for the follow-up calls. The files themselves move through the authorized transfer path, RIPTON Desktop or an automation node, using the transfer spec for that package.

  6. Check state from the terminal

    List running transfers and the jobs overview to see what your automation created and where it stands.

  7. Close the loop with a webhook

    Subscribe a webhook to package.status_changed so the calling system learns when the package completes, instead of polling. The webhook guide covers it.

Commands and reference

export RIPTON_SERVER=https://ripton.example.com
export RIPTON_ACCESS_TOKEN="$(secret-tool lookup ripton nightly-export)"   # or your secret manager's equivalent

ripton nodes list --query enabled=true
ripton transfers list --query status=running
ripton jobs overview
curl -fsS -X POST "$RIPTON_SERVER/api/v1/packages" \
  -H "Authorization: Bearer $RIPTON_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Nightly export 2026-09-13",
    "note": "Created by nightly-export",
    "recipients": ["ops@partner.example"],
    "expires_at": "2026-09-20T00:00:00Z"
  }'

How you know it worked

  • ripton nodes list returns your nodes; a command outside the granted scopes is refused.
  • The package created by the script appears in the admin Packages page with the expected title and recipients.
  • Rotating the client's secret invalidates the old token on the next call.

If something is off

What you seeWhat to do
401 or 403 from every callThe token is missing or the client lacks the scope. Check RIPTON_ACCESS_TOKEN is set in the same shell and that the client has the scope for the operation.
The package is created but stays in uploadingCreating the package records it; the bytes still have to move. Confirm the automation host runs the transfer step with the package's transfer spec, and watch the transfer in Admin, then Transfers.
Rate limitedPoll less often, or replace polling with a webhook subscription.