Sandbox

Use a separate profile with sandbox credentials to test your integration without touching production. The CLI adds two commands to the sandbox group: cademi sandbox reset erases and reseeds the sandbox, and cademi sandbox run runs a test scenario that produces real events.

Sign in to the sandbox

Sandbox credentials are issued in your sandbox account and their secrets start with ck_test_. The sandbox uses the same platform URL as production. Save it as its own profile:

cademi auth login --profile sandbox
cademi --profile sandbox sandbox get

cademi sandbox get shows the state of the sandbox and when it was last reset. With production credentials, it tells you whether a sandbox exists. cademi auth status shows the environment of the current credentials. How to provision a sandbox and what it simulates are described in Sandbox.

To run a sequence of commands against the sandbox, switch the current profile:

cademi profiles use sandbox

Reset the sandbox

cademi sandbox reset

The command first confirms with the API that the current credentials belong to a sandbox, and refuses to run otherwise (exit code 2). It then asks for confirmation, requests the reset, and waits for the reset operation to finish. The reset deletes the sandbox data, including uploaded files, and seeds the fixed test data again. Credentials, administrators, limits, and the audit trail are kept. Production is never affected.

The credentials need sandbox.manage. A second reset requested while one is running returns 409 state_conflict. If the reset operation fails, the command exits with code 1.

Run test scenarios

Test scenarios create records marked as simulated and emit the same public events as production, which reach webhook endpoints and cademi listen.

cademi sandbox test-scenarios list
cademi sandbox test-scenarios get scn_01J8Z3...
cademi sandbox run scn_01J8Z3...
cademi sandbox run scn_01J8Z3... --param <name>=<value>

cademi sandbox test-scenarios get shows the parameters a scenario accepts (params) and its effects (effects): what it creates and the events it emits. Pass each parameter with --param name=value. Values are typed like -F: true, false, null, numbers, and JSON are converted, and anything else is sent as a string.

cademi sandbox run starts the scenario, waits for its operation to finish, and prints the operation. It then prints the result of the run to standard error, with the number of records created by type and the number of events emitted. If the operation fails, the command exits with code 1. --no-wait returns as soon as the operation is created.

The credentials need sandbox.read to list scenarios and sandbox.manage to run them. Outside a sandbox, the API returns 409 sandbox_required and the command exits with code 6. A reset deletes everything the scenarios created.

Test a webhook receiver end to end

1. Start your application locally, then forward events to it:

cademi --profile sandbox listen --forward-to localhost:3000/webhooks/cademi

2. Configure your receiver with the local signing secret from cademi --profile sandbox listen --print-secret.
3. In another terminal, run a scenario:

cademi --profile sandbox sandbox run scn_01J8Z3...

4. Each event appears in the first terminal with the status code your application returned.

See Events with cademi listen and Event streams.

Failure scenarios

The sandbox is the place to trigger error responses and check how your scripts react to them. Sandbox lists how to trigger each one, and Exit codes lists the exit code the CLI returns for each class of error.