CLI command
skarbiec subscription run
Sign every subscription grant that is due in again through Weles, reached as Stado's browser-automation family; each skarbiec maintain pass does the same.
Invocation#
skarbiec subscription run [--item <item-id> [--now]]Purpose#
Sign every subscription grant that is due in again through Weles, reached as Stado's browser-automation family; each skarbiec maintain pass does the same.
Required inputs and options#
- No input signs in every due grant; --item only that subscription's when it is due; --item with --now that subscription's whatever its standing. POST /v1/operator/subscriptions/run takes item and now. Stado is STADO_BIN, else stado on PATH.
Output and state effects#
- A grant is due when the item holds none, or a consumer recorded that the provider refused the grant it holds now. For each due one Skarbiec runs `stado capabilities call browser-automation --operation subscription-sign-in --consumer skarbiec --json` with {"provider", "subscription"} (the item's brama:provider: and brama:id: tags) on standard input; Stado runs the alternative that answers the family, Weles's `weles accounts refresh`, which signs the account in on its Stado-selected browser host and stores the grant on the item. The sign-in counts only once the vault holds a newer revision of the item whose grant differs from the one it held when the run chose it; a write that keeps the same grant (a retag, metadata a consumer added) is not a sign-in. Each outcome is written on the subscription's record (last_attempt_at, last_status signed_in, held or retry, last_error, last_run, last_cause the declared cause id it failed for, last_due why the grant was due, and the footing the decision stands on, read from the vault as it is after the attempt) and journalled as subscription-signed-in or subscription-sign-in-failed; the record keeps the last attempt only, and the journal every attempt. A sign-in removes the refusal. A sign-in refused for a cause asking again unchanged will not change is held: it is not asked for again until the refusal, the item's revision, the login item's revision, the tags or what blocks it change, or --now asks for it, so one verdict never opens a browser or pages a person twice, even when Weles wrote the item before it refused. A failure asking again can change leaves the grant due for the next pass. Prints ok, ran (each item, provider, subscription_id, due, cause, status, revision, run, error: due is why the grant was due, cause the declared cause id of a failure) and failed.
Refusals#
- Every refusal is a declared cause of skarbiec.subscription under /docs/errors. A flag the form does not take exits 2 (flag-unknown), as does --now without --item (now-without-item). --item naming an item that is no live subscription is refused listing the subscriptions (not-subscription). On a replica the run is refused naming the source to run it on. Each sign-in that does not succeed is recorded on its subscription and the run then exits 1 with `signing the due subscriptions in: <count> subscription sign-in(s) did not succeed (<alert>): <items>` (run-refused), the report carrying each one's cause: unsignable (no single brama:provider:, brama:id: or brama:login: tag, a login item that is not a live item or does not open, or a login whose recorded second factor is an authenticator code the vault keeps no seed for (missing-seed) or a seed that computes none (invalid), named before Stado is asked, so no browser starts; held), grant-unreadable (the item does not open with the keys this host holds; left due), stado-absent (no stado on PATH and no STADO_BIN; left due), stado-unstarted (the stado named cannot start; left due), stado-answer-unreadable (stado printed no JSON and no failure envelope, as a Stado older than the subscription-sign-in operation does; left due), sign-in-unavailable (Stado's error_code is infra_down, rate_limit or timeout: no alternative could sign it in now; left due), sign-in-refused (any other error_code: the sign-in ran and was refused, or no alternative is declared here; held), sign-in-unconfirmed (Weles answered the sign-in finished and the item holds no newer revision, or a newer one with no grant, or with the same grant it held before the sign-in; held). Where `alert set` is set the failure is posted there too.
- skarbiec.subscription form-unknown — exit 2: reading what skarbiec subscription is asked; fix: run subscription list, refuse, withdraw or run; skarbiec subscription help lists them
- skarbiec.subscription flag-unknown — exit 2: reading the flags of subscription {verb}; fix: drop --{flag}; subscription {verb} takes {takes}
- skarbiec.subscription item-argument — exit 2: reading which subscription subscription {verb} acts on; fix: name one item `skarbiec subscription list` shows: skarbiec subscription {verb} <item-id> …
- skarbiec.subscription reason-missing — exit 2: recording that the provider refused the grant of {item}; fix: pass the provider's answer: skarbiec subscription refuse {item} --reason '<what the provider said>'
- skarbiec.subscription now-without-item — exit 2: signing one subscription in before it is due; fix: name it: skarbiec subscription run --item <item-id> --now
- skarbiec.subscription not-subscription — exit 1: reading the subscription {item}; fix: name an item `skarbiec subscription list` shows; a subscription is a live item tagged brama:subscription
- skarbiec.subscription section-malformed — exit 1: reading the vault's subscription sign-in records; fix: run skarbiec upgrade to see what it can read; withdraw each damaged record with subscription withdraw, which writes it again
- skarbiec.subscription no-refusal — exit 1: withdrawing the recorded refusal of {item}; fix: name an item whose grant `skarbiec subscription list` shows as refused
- skarbiec.subscription unsignable — exit 1: signing the subscription {item} in; fix: tag {item} with exactly one brama:provider:<provider>, brama:id:<subscription id> and brama:login:<login item> (skarbiec retag --add <tag> {item}), naming a login item that exists and opens here, whose recorded second factor the vault can answer (skarbiec login factor list <login item> names what it lacks; skarbiec totp set adds a seed), then run skarbiec subscription run --item {item} --now
- skarbiec.subscription grant-unreadable — exit 69: reading the stored grant of the subscription {item}; fix: open it by hand (skarbiec get {item}) and repair what that names; skarbiec doctor names a missing key
- skarbiec.subscription stado-absent — exit 1: asking Stado's browser-automation family to sign {item} in; fix: install Stado (it puts stado on PATH), or point STADO_BIN at the installed stado
- skarbiec.subscription stado-unstarted — exit 69: asking Stado's browser-automation family to sign {item} in; fix: make {program} an executable Stado ({program} --version answers when it is), or point STADO_BIN at one
- skarbiec.subscription stado-answer-unreadable — exit 1: reading what Stado answered for the sign-in of {item}; fix: run the command above by hand and repair what it says; a Stado older than the browser-automation operation subscription-sign-in is updated with stado product update stado
- skarbiec.subscription sign-in-unavailable — exit 69: signing the subscription {item} ({provider} {subscription}) in; fix: {remedy}; the next skarbiec maintain or skarbiec subscription run asks again
- skarbiec.subscription sign-in-refused — exit 1: signing the subscription {item} ({provider} {subscription}) in; fix: {remedy}; then skarbiec subscription run --item {item} --now
- skarbiec.subscription sign-in-unconfirmed — exit 1: confirming the sign-in of the subscription {item}; fix: read the run Weles names (weles runs show <run>), repair why its grant did not reach {item}, then skarbiec subscription run --item {item} --now
- skarbiec.subscription run-refused — exit 1: signing the due subscriptions in; fix: read each subscription's last_error with skarbiec subscription list and act on it; the other due sign-ins ran
- skarbiec.subscription report-unknown — exit 1: finding the subscription {subscription} of {provider} a consumer named; fix: send the provider and subscription id the subscription item's own tags carry (skarbiec subscription list names both)
- skarbiec.subscription report-ambiguous — exit 1: finding the subscription {subscription} of {provider} a consumer named; fix: keep the id on one item: skarbiec retag --remove brama:id:{subscription} <item> on each other one
- skarbiec.subscription report-not-granted — exit 1: answering {route} for {consumer}; fix: add report:subscriptions to {consumer}'s grant on the vault owner (skarbiec grant list shows its capabilities; Brama's launcher issues it to brama-subscription-reporter at each start), then present that grant's bearer
- skarbiec.subscription report-stale — exit 1: recording that the provider refused the grant of subscription {item}, as {by} reported it; fix: read the grant {item} holds now and present it; report a refusal of that grant if the provider refuses it too
- skarbiec.subscription report-grant-malformed — exit 2: reading which grant {consumer} reports refused; fix: send the SHA-256 of the grant's JSON with its object members in name order and no whitespace, as 64 hexadecimal digits, or leave grant_sha256 out