Run a long command

briq_exec waits for a command for up to a minute. Anything longer (a build, a test suite, a data load, a migration) runs with async: true: briq starts it, answers at once with an exec id, and you check it until it ends. First, connect your agent.

briq_exec({ briq: "bq_…", cmd: ["sh", "-c", "cd /app && npm ci && npm test"], async: true })
→ ex_7kq2m9x1p4ab running since 10:02 UTC; stopped at 11:02 UTC if still running

briq_exec_result({ briq: "bq_…", exec: "ex_7kq2m9x1p4ab" })
→ ex_7kq2m9x1p4ab exited 0 after 3m
  stdout: …

1. The command runs in the briq, in the background, under sh.
2. briq_exec_result waits up to 30 seconds for it to end, then answers either way. Call it again while it runs.
3. Its answer has the state, the exit code once it ends, and the last 64 KB of stdout and stderr.

Read all of the output

The whole output stays in the briq, in /tmp/.briq/exec/<exec id>/out and err:

briq_files_get({ briq: "bq_…", path: "/tmp/.briq/exec/ex_7kq2m9x1p4ab/out" })

Over 1 MB, read part of it with briq_exec: ["tail", "-n", "200", "/tmp/.briq/exec/ex_…/out"].

Stop it

briq_exec_stop({ briq: "bq_…", exec: "ex_7kq2m9x1p4ab" })
→ ex_7kq2m9x1p4ab stopped on request

It stops the command and every process it started.

Set a deadline

timeoutMs stops the command when it runs out: one hour by default, 24 hours at most.

briq_exec({ briq: "bq_…", cmd: ["make", "release"], async: true, timeoutMs: 14400000 })

Over REST

EXEC=$(curl -sf "https://api.briq.cloud/v1/briqs/$ID/exec" -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" -d '{ "cmd": ["make", "test"], "async": true }' | jq -r .exec.id)
until STATE=$(curl -sf "https://api.briq.cloud/v1/briqs/$ID/execs/$EXEC?waitMs=45000" \
  -H "Authorization: Bearer $BRIQ_API_KEY") && [ "$(jq -r .exec.state <<<"$STATE")" != running ]; do sleep 5; done
jq -r .exec.output.stdout <<<"$STATE"

States

When it does not work

• an async exec needs sh in the image (or setsid): the image has neither (distroless, scratch). Run the command without async (up to a minute), or use an image that has them.
• 10 commands are already running: a briq runs ten at most. Wait for one, or stop one.
• warning: timeoutMs is at most 60000 without async: the command ran for a minute at most. Run it again with async: true.
• lost: the machine started again from scratch and the command did not survive (a crash, or a stop and start of a briq too large to resume from memory). Start the command again.
• the briq is stopped, so the command cannot be reached: briq_start the briq, then stop the command. A check on a stopped briq answers with the last state seen.

Good to know

• A running command keeps its stack awake, and billed, until it ends or reaches its deadline, whatever the sleep setting or a key's maxSleep. See Sleep.
• Lost an exec id? briq_status lists the briq's running commands.
• Checking is use too, like any call on the stack.
• Input: stdin works as with briq_exec.
• The output files stay in the briq until it is destroyed.