vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/commands/agents/suggestion/suggestion_feedback.py

@@ -0,0 +1,85 @@
+"""Registers explicit accepted and rejected suggestion feedback commands.
+
+Feedback is appended to one project's local JSON memory and never inferred from silence or
+implementation. This module owns Click parsing and result rendering; validation and
+persistence belong to `SuggestionFeedbackInput` and `SuggestionProject`.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ....lib.errors.failures import SuggestionFeedbackInvalid, SuggestionProjectInvalid
+from ....lib.output import OutputDocument
+from ....lib.runtime.context import ApplicationContext as Context
+from ....services.suggestions.project import (
+    SuggestionFeedbackInput,
+    SuggestionProject,
+    SuggestionProjectKey,
+)
+from ....types.suggestions import FeedbackType
+from .prompts.library import SuggestionHelpLibrary
+
+_HELP = SuggestionHelpLibrary()
+_GROUP_HELP = _HELP.load("feedback_group")
+_ACCEPT_HELP = _HELP.load("feedback_accept")
+_REJECT_HELP = _HELP.load("feedback_reject")
+_PROJECT_HELP = _HELP.load("feedback_project")
+_SUGGESTION_HELP = _HELP.load("feedback_suggestion")
+_REASON_HELP = _HELP.load("feedback_reason")
+
+
+class SuggestionFeedbackGroup:
+    """Attaches accepted and rejected feedback verbs below the suggest group."""
+
+    def register(self, parent: click.Group) -> None:
+        # Keeps both dispositions on one command family with one persistence implementation.
+        feedback = click.Group(name="feedback", help=_GROUP_HELP)
+        SuggestionFeedbackCommand(FeedbackType.ACCEPTED).register(feedback)
+        SuggestionFeedbackCommand(FeedbackType.REJECTED).register(feedback)
+        parent.add_command(feedback)
+
+
+class SuggestionFeedbackCommand:
+    """Validates and appends one explicit accepted or rejected reaction."""
+
+    def __init__(self, feedback_type: FeedbackType) -> None:
+        # The disposition is fixed by registration so callers cannot pass arbitrary types.
+        self._feedback_type = feedback_type
+
+    def register(self, parent: click.Group) -> None:
+        # Adds one verb whose name and help match its fixed disposition.
+        accepted = self._feedback_type is FeedbackType.ACCEPTED
+
+        @parent.command(
+            name="accept" if accepted else "reject",
+            help=_ACCEPT_HELP if accepted else _REJECT_HELP,
+        )
+        @click.option("--project", required=True, help=_PROJECT_HELP)
+        @click.option("--suggestion", required=True, help=_SUGGESTION_HELP)
+        @click.option("--reason", default=None, help=_REASON_HELP)
+        @click.pass_obj
+        def _feedback(ctx: Context, project: str, suggestion: str, reason: str | None) -> None:
+            self.execute(ctx, project, suggestion, reason)
+
+    def execute(self, context: Context, project: str, suggestion: str, reason: str | None) -> None:
+        # A malformed key and malformed feedback name different options, so they fail apart.
+        try:
+            key = SuggestionProjectKey(project)
+        except (TypeError, ValueError) as error:
+            raise SuggestionProjectInvalid(str(error)) from error
+        try:
+            request = SuggestionFeedbackInput(key, self._feedback_type, suggestion, reason)
+        except (TypeError, ValueError) as error:
+            raise SuggestionFeedbackInvalid(str(error)) from error
+        record = SuggestionProject(context.paths()).record_feedback(request)
+        context.output().result(
+            OutputDocument(
+                kind="suggestions.feedback.recorded",
+                data={"project": key.value, "feedback": record.model_dump(mode="json")},
+            ),
+            f"Recorded {record.type.value} feedback for '{key.value}'.",
+        )
+
+
+__all__ = ["SuggestionFeedbackGroup"]

vidbyte_cli/commands/agents/suggestion/suggestion_handoff.py

@@ -0,0 +1,67 @@
+"""Extracts one handoff from a saved suggestion result without a model.
+
+The command reads a `suggestions.result` document, selects one idea by id,
+and emits its handoff as `suggestions.handoff`. This is a pure local read, so
+it never needs credentials and never calls a provider on any code path.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from ....lib.errors.failures import SuggestionContextUnreadable, SuggestionInputInvalid
+from ....lib.runtime.context import ApplicationContext as Context
+from ....types.suggestions import SuggestionHandoff, SuggestionResult
+from .prompts.library import SuggestionHelpLibrary
+from .render import SuggestionRenderer
+
+_HELP = SuggestionHelpLibrary()
+_COMMAND_HELP = _HELP.load("handoff")
+_INPUT_HELP = _HELP.load("input")
+_IDEA_HELP = _HELP.load("idea")
+
+
+class SuggestionHandoffCommand:
+    """Reads a saved batch and renders one deterministic handoff packet."""
+
+    def register(self, parent: click.Group) -> None:
+        # Attaches handoff with input and idea selectors as its only options.
+        @parent.command(name="handoff", help=_COMMAND_HELP)
+        @click.option(
+            "--input",
+            "input_path",
+            required=True,
+            type=click.Path(path_type=Path),
+            help=_INPUT_HELP,
+        )
+        @click.option("--idea", required=True, help=_IDEA_HELP)
+        @click.pass_obj
+        def _handoff(ctx: Context, input_path: Path, idea: str) -> None:
+            # Delegates to the execution method for direct testing.
+            self.execute(ctx, input_path, idea)
+
+    def execute(self, context: Context, input_path: Path, idea: str) -> None:
+        # Validates the document, selects the idea, and emits its handoff.
+        result = self._load(input_path)
+        selected = next((item for item in result.ideas if item.id == idea.strip()), None)
+        if selected is None:
+            raise SuggestionInputInvalid()
+        handoff = SuggestionHandoff.model_validate(selected.handoff.model_dump(mode="json"))
+        SuggestionRenderer().render_handoff(context, handoff)
+
+    def _load(self, input_path: Path) -> SuggestionResult:
+        # Rejects missing, malformed, and wrong-kind documents before selecting.
+        try:
+            text = Path(input_path).read_text(encoding="utf-8-sig")
+            document = json.loads(text)
+        except (OSError, json.JSONDecodeError) as error:
+            raise SuggestionContextUnreadable(str(error)) from error
+        if not isinstance(document, dict) or document.get("kind") != "suggestions.result":
+            raise SuggestionInputInvalid()
+        try:
+            return SuggestionResult.model_validate(document.get("data", document))
+        except Exception as error:
+            raise SuggestionContextUnreadable(str(error)) from error

vidbyte_cli/commands/agents/suggestion/suggestion_projects.py

@@ -0,0 +1,95 @@
+"""Registers local suggestion project creation and catalog listing commands.
+
+Projects are small, credential-free local records that give later suggestion runs a stable
+memory scope. This module owns Click parsing and output only; what a project is and how it is
+stored belong to `SuggestionProject`.
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+import click
+from pydantic import JsonValue
+
+from ....lib.errors.failures import SuggestionProjectInvalid
+from ....lib.output import OutputDocument
+from ....lib.runtime.context import ApplicationContext as Context
+from ....services.suggestions.project import (
+    SuggestionProject,
+    SuggestionProjectCreateInput,
+    SuggestionProjectKey,
+)
+from .prompts.library import SuggestionHelpLibrary
+
+_HELP = SuggestionHelpLibrary()
+_GROUP_HELP = _HELP.load("project_group")
+_CREATE_HELP = _HELP.load("project_create")
+_LIST_HELP = _HELP.load("project_list")
+_KEY_HELP = _HELP.load("project_key")
+_TITLE_HELP = _HELP.load("project_title")
+_DESCRIPTION_HELP = _HELP.load("project_description")
+
+
+class SuggestionProjectGroup:
+    """Attaches project create and list commands below the suggest group."""
+
+    def register(self, parent: click.Group) -> None:
+        # Keeps project verbs together without adding persistence logic to registration.
+        project = click.Group(name="project", help=_GROUP_HELP)
+        SuggestionProjectCreateCommand().register(project)
+        SuggestionProjectListCommand().register(project)
+        parent.add_command(project)
+
+
+class SuggestionProjectCreateCommand:
+    """Validates and creates one local suggestion project."""
+
+    def register(self, parent: click.Group) -> None:
+        # Click owns required-field errors while the input dataclass owns domain validation.
+        @parent.command(name="create", help=_CREATE_HELP)
+        @click.option("--key", required=True, help=_KEY_HELP)
+        @click.option("--title", required=True, help=_TITLE_HELP)
+        @click.option("--description", required=True, help=_DESCRIPTION_HELP)
+        @click.pass_obj
+        def _create(ctx: Context, key: str, title: str, description: str) -> None:
+            self.execute(ctx, key, title, description)
+
+    def execute(self, context: Context, key: str, title: str, description: str) -> None:
+        # Every field is validated before the catalog is read, so a bad value writes nothing.
+        try:
+            request = SuggestionProjectCreateInput(SuggestionProjectKey(key), title, description)
+        except (TypeError, ValueError) as error:
+            raise SuggestionProjectInvalid(str(error)) from error
+        project = SuggestionProject(context.paths()).create(request)
+        context.output().result(
+            OutputDocument(
+                kind="suggestions.project.created", data=project.model_dump(mode="json")
+            ),
+            f"Created suggestion project '{project.key}'.",
+        )
+
+
+class SuggestionProjectListCommand:
+    """Reads and renders the local suggestion project catalog."""
+
+    def register(self, parent: click.Group) -> None:
+        # Catalog listing is read-only and remains available without credentials.
+        @parent.command(name="list", help=_LIST_HELP)
+        @click.pass_obj
+        def _list(ctx: Context) -> None:
+            self.execute(ctx)
+
+    def execute(self, context: Context) -> None:
+        # Renders project summaries only; feedback bodies stay in their own files.
+        projects = SuggestionProject(context.paths()).list_projects()
+        data: dict[str, JsonValue] = {
+            "projects": [cast(JsonValue, project.model_dump(mode="json")) for project in projects]
+        }
+        human = "\n\n".join(
+            f"{project.key}  {project.title}\n  {project.description}" for project in projects
+        )
+        context.output().result(OutputDocument(kind="suggestions.projects", data=data), human)
+
+
+__all__ = ["SuggestionProjectGroup"]

vidbyte_cli/commands/auth/login.py

@@ -0,0 +1,100 @@
+"""`vidbyte-cli login` — stores the user's Vidbyte API key for later commands.
+
+There is no `--api-key` option: a secret in argv leaks into `ps`, shell history, and CI
+logs. `--with-token` reads bounded stdin; anything else uses a hidden prompt.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ...lib.auth import CredentialStorage
+from ...lib.auth.input import CredentialInput
+from ...lib.errors.failures import FileFallbackNotApproved
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext
+
+
+class LoginCommand:
+    def register(self, parent: click.Group) -> None:
+        # Attaches `login` to the root program.
+        @parent.command(name="login", help="Authenticate with a Vidbyte API key")
+        @click.option(
+            "--with-token",
+            is_flag=True,
+            help="Read the API key from stdin instead of a hidden prompt.",
+        )
+        @click.option(
+            "--allow-file-fallback",
+            is_flag=True,
+            help="Approve restricted-file storage when no OS keyring is available.",
+        )
+        @click.pass_obj
+        def _run(
+            context: ApplicationContext,
+            with_token: bool,
+            allow_file_fallback: bool,
+        ) -> None:
+            self.execute(context, with_token, allow_file_fallback)
+
+    def execute(
+        self,
+        context: ApplicationContext,
+        with_token: bool,
+        allow_file_fallback: bool,
+    ) -> None:
+        config = context.resolved_config()
+        credentials = CredentialInput(
+            context.streams,
+            context.output().terminal,
+            no_input=context.options.no_input,
+        ).read(from_stdin=with_token)
+        # Verify-before-persist. Syntactic checks cannot prove a key authenticates, and this
+        # call sits immediately before the only write so a reordering is obvious in review.
+        context.credential_verifier().verify(credentials, config)
+        fallback_allowed = self._fallback_consent(context, allow_file_fallback)
+        # Legacy state moves only on an explicit mutation, never on a read path.
+        context.migration().migrate_if_needed()
+        storage = context.credential_store().write(
+            credentials,
+            config.profile,
+            config.api_url,
+            allow_file_fallback=fallback_allowed,
+        )
+        if storage is CredentialStorage.RESTRICTED_FILE:
+            context.output().warning(
+                "The API key is stored in a permission-restricted file because no OS "
+                "keyring is available."
+            )
+        context.output().result(
+            OutputDocument(
+                kind="auth.login",
+                data={
+                    "profile": config.profile,
+                    "api_url": config.api_url,
+                    "storage": storage.value,
+                },
+            ),
+            f"Authenticated profile '{config.profile}' using {storage.value}.",
+        )
+
+    def _fallback_consent(
+        self,
+        context: ApplicationContext,
+        explicitly_allowed: bool,
+    ) -> bool:
+        # The fallback file is readable by anything running as this user, so consent is the
+        # caller's to give — asked for here only when there is a terminal to ask on.
+        if context.credential_store().keyring.available():
+            return False
+        if explicitly_allowed:
+            return True
+        if context.options.no_input or not context.output().terminal.interactive:
+            raise FileFallbackNotApproved()
+        return bool(
+            click.confirm(
+                "No OS keyring is available. Store the key in a restricted local file?",
+                default=False,
+                err=True,
+            )
+        )

vidbyte_cli/commands/auth/logout.py

@@ -0,0 +1,41 @@
+"""`vidbyte-cli logout` — removes stored credentials from this machine.
+
+Logout is a desired state, not an action that must have had something to undo: an
+already-logged-out profile succeeds, so a cleanup script can run it unconditionally.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext
+
+
+class LogoutCommand:
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="logout", help="Remove stored Vidbyte credentials from this machine")
+        @click.pass_obj
+        def _run(context: ApplicationContext) -> None:
+            self.execute(context)
+
+    def execute(self, context: ApplicationContext) -> None:
+        # Scoped to the selected profile and API host: logging out of staging must leave the
+        # production credential alone.
+        config = context.resolved_config()
+        removed = context.credential_store().clear(config.profile, config.api_url)
+        context.output().result(
+            OutputDocument(
+                kind="auth.logout",
+                data={
+                    "profile": config.profile,
+                    "api_url": config.api_url,
+                    "removed": removed,
+                },
+            ),
+            (
+                f"Removed credentials for profile '{config.profile}'."
+                if removed
+                else f"Profile '{config.profile}' was already logged out."
+            ),
+        )

vidbyte_cli/commands/auth/whoami.py

@@ -0,0 +1,51 @@
+"""`vidbyte-cli whoami` — shows which account the stored credentials belong to.
+
+The identity comes from the same backend check login uses, so the two commands can never
+disagree about whether a key is good. Reading is done through `CredentialResolver`, which puts
+`VIDBYTE_API_KEY` ahead of the keyring — correct here, because that is the key later commands
+would actually send.
+"""
+
+from __future__ import annotations
+
+import click
+from pydantic import JsonValue
+
+from ...lib.errors.failures import AuthenticationRequired
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext
+
+
+class WhoamiCommand:
+    def register(self, parent: click.Group) -> None:
+        # Attaches `whoami` to the root program.
+        @parent.command(name="whoami", help="Show the account behind the stored credentials")
+        @click.pass_obj
+        def _run(context: ApplicationContext) -> None:
+            self.execute(context)
+
+    def execute(self, context: ApplicationContext) -> None:
+        # Resolves the stored credential, proves it against the backend, and prints the identity.
+        config = context.resolved_config()
+        credential = context.credential_resolver().resolve(config.profile, config.api_url)
+        if credential is None:
+            # Raised before any request, so an unauthenticated machine never reaches the network.
+            raise AuthenticationRequired()
+        identity = context.credential_verifier().verify(credential.credentials, config)
+        data: dict[str, JsonValue] = {
+            "profile": config.profile,
+            "api_url": config.api_url,
+            "username": identity.username,
+            "account_tier": identity.account_tier,
+            "credential_source": credential.source.value,
+        }
+        human = "\n".join(
+            (
+                f"Authenticated as: {identity.username}",
+                f"Account tier: {identity.account_tier}",
+                f"Profile: {config.profile}",
+                f"API URL: {config.api_url}",
+                f"Credential source: {credential.source.value}",
+            )
+        )
+        context.output().result(OutputDocument(kind="auth.whoami", data=data), human)

vidbyte_cli/commands/billing/__init__.py

@@ -0,0 +1,20 @@
+"""Commands for explicitly funding the authenticated Vidbyte API balance."""
+
+import click
+
+from .prompts.library import BillingHelpLibrary
+from .top_up import BillingTopUpCommand
+
+_GROUP_HELP = BillingHelpLibrary().load("group")
+
+
+class BillingCommandGroup:
+    """Registers billing commands beneath the CLI's top-level billing group."""
+
+    def register(self, parent: click.Group) -> None:
+        billing = click.Group(name="billing", help=_GROUP_HELP)
+        BillingTopUpCommand().register(billing)
+        parent.add_command(billing)
+
+
+__all__ = ["BillingCommandGroup", "BillingTopUpCommand"]

vidbyte_cli/commands/billing/prompts/__init__.py

@@ -0,0 +1 @@
+"""Markdown assets used by billing command help."""

vidbyte_cli/commands/billing/prompts/confirm.md

@@ -0,0 +1,16 @@
+# `--confirm`
+
+## Purpose
+This required opt-in authorizes the billing command to proceed toward a paid Vidbyte API-balance top-up. Supplying it means the caller has obtained the user's explicit approval for a minimum five-dollar purchase. Without it, the command exits before resolving credentials, constructing a signer, or sending an HTTP request. It does not approve unrelated charges or authorize a later top-up. Error handling in other commands never adds this flag automatically.
+
+## Default and when to use
+The default is off, so omitting the flag cannot create a payment authorization. Add it only when the user has reviewed the amount and asked to fund the Vidbyte API balance. Do not infer approval from an earlier request to run research or from a prior top-up. If the user has not approved spending, leave the flag out and stop at the recovery instructions. The command does not prompt interactively in place of this explicit choice.
+
+## Payment boundary
+With confirmation present, the command still pays only the exact challenge returned by `POST /agent/topup`. The endpoint controls the accepted amount, network, asset, and recipient. The flag does not expose or print the private key and does not authorize payment to a different endpoint. If payment configuration is missing or the challenge is invalid, the command fails without launching an agent. Provider-model charges are outside this confirmation and remain governed by the provider account.
+
+## Examples
+After user approval, run `vidbyte-cli billing top-up --confirm` to create a new top-up request. To recover the same uncertain request, pass the original key as `--idempotency-key` along with `--confirm`. Do not combine confirmation with a new key when recovering an uncertain payment, because a new key can represent a second charge. After success, verify the available balance before retrying the original operation. If approval is absent, run no payment command.
+
+## Related commands
+The parent command is `vidbyte-cli billing top-up`. Its help explains account setup, payment behavior, output, and recovery. The idempotency option's help explains how to reuse a key after an uncertain response. Neither option changes the requirement for explicit user approval. The browser fallback is <https://vidbyte.pro/settings/api>.

vidbyte_cli/commands/billing/prompts/group.md

@@ -0,0 +1,13 @@
+# Billing commands
+
+## Purpose
+The billing group contains explicit operations for managing the Vidbyte API balance used by API-key requests. Its commands interact with Vidbyte billing endpoints and do not manage model-provider accounts. Billing actions that spend money require a separate explicit command invocation and user approval. A failed research or runtime command never calls a billing command automatically. Read the child command help before making a purchase.
+
+## Available command
+Use `billing top-up` to add the backend's minimum five-dollar credit to the API balance associated with the configured Vidbyte key. The top-up command pays the exact x402 challenge returned by the billing endpoint. It reports the credited amount and the balance available afterward. It does not start or resume any prior operation. After a top-up, confirm the balance and then decide whether the original operation should be retried or resumed.
+
+## Approval and credentials
+Obtain explicit approval from the user before invoking a paid billing action. Configure the same Vidbyte API key that made the request requiring more balance. Configure any payment signer through the supported environment variable and never pass its secret as a command argument. The command requires `--confirm` before it resolves credentials or sends HTTP. If the user has not approved a purchase, stop and use the account settings page instead.
+
+## Recovery and related commands
+When a top-up response is uncertain, repeat the same top-up with its original idempotency key so the backend can recover that purchase. A new key represents a distinct operation and can create an additional charge. The idempotency key from the failed research operation is separate and should remain unchanged when retrying that operation. If payment cannot be completed in the CLI, visit <https://vidbyte.pro/settings/api> to manage API balance in a browser. Provider charges for model usage remain separate from Vidbyte API balance.

vidbyte_cli/commands/billing/prompts/idempotency_key.md

@@ -0,0 +1,16 @@
+# `--idempotency-key`
+
+## Purpose
+This option identifies one top-up operation to the backend so a repeated request can recover the same result instead of creating a second purchase. For a new top-up, leave it unset and the CLI creates a fresh key. For a retry after a timeout or lost response, provide exactly the key used by the original attempt. The key applies only to this top-up and does not replace the key from the failed research or runtime operation. Reusing a key does not itself prove that payment succeeded; inspect the returned balance.
+
+## Defaults and recovery
+The default is no caller-provided key, which causes the CLI to generate one for a new purchase. Supply a key only when recovering the same top-up whose outcome is uncertain. Keep the value identical across retries and preserve it somewhere safe until the outcome is known. Do not reuse a completed top-up's key for a separate purchase. Do not generate a replacement key just because the first response was missing, since that can create another charge.
+
+## Accepted value
+Pass one stable string of 8 to 128 letters, digits, dots, underscores, colons, or hyphens. Avoid including account data, credentials, or other secrets in the value. The key is sent to the Vidbyte API as the idempotency identifier for the top-up request. The same key must accompany both the unpaid challenge request and the paid retry. The CLI does not print the payment authorization as part of its result.
+
+## Examples
+Start a new approved purchase with `vidbyte-cli billing top-up --confirm` and let the CLI generate a key. If that request times out, repeat it with `vidbyte-cli billing top-up --confirm --idempotency-key <same-key>`. Replace the placeholder with the exact key from the original request rather than the literal angle-bracket text. Confirm the balance returned by the API before retrying the original operation. Use a different fresh key only for a distinct top-up after a separate user approval.
+
+## Related commands
+The parent `vidbyte-cli billing top-up` help describes the charge and the post-payment recovery sequence. `--confirm` remains mandatory for both new and recovered attempts. The original failed operation's idempotency key is separate and must be retained for retrying that operation. Use <https://vidbyte.pro/settings/api> when the caller cannot safely make the payment through this command.

vidbyte_cli/commands/billing/prompts/library.py

@@ -0,0 +1,18 @@
+"""Loads caller-facing billing help from packaged Markdown assets."""
+
+from __future__ import annotations
+
+from importlib import resources
+
+
+class BillingHelpLibrary:
+    """Reads each billing help description from its named Markdown asset."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, str] = {}
+
+    def load(self, name: str) -> str:
+        if name not in self._cache:
+            asset = resources.files(__package__).joinpath(f"{name}.md")
+            self._cache[name] = asset.read_text(encoding="utf-8").strip()
+        return self._cache[name]

vidbyte_cli/commands/billing/prompts/top_up.md

@@ -0,0 +1,16 @@
+# Billing top-up
+
+## Purpose
+Use this command to add the backend's minimum five-dollar credit to the Vidbyte API balance associated with the configured API key. The command does not top up a model-provider account or change the provider credentials used by a research run. It sends `POST /agent/topup` and pays the exact x402 challenge returned by that endpoint. The backend response reports the amount credited and the remaining available balance. Call this command only after the account owner has approved the purchase.
+
+## When to use
+Use this command after a Vidbyte API-balance error when the user has approved a charge and wants to continue the original operation. Before running it, configure the API key for the same Vidbyte account that received the error. Configure the x402 private key through the supported environment variable without pasting it into a command, prompt, or log. If a payment result is uncertain, reuse the idempotency key from that same top-up instead of creating a new purchase. If payment setup is unavailable, the user can add balance at <https://vidbyte.pro/settings/api>.
+
+## Approval and cost
+This command creates a real payment authorization and must never be invoked as an automatic error-recovery side effect. Obtain explicit user approval before adding `--confirm`. The API determines the exact payment challenge; this CLI does not let the caller select a different amount, rail, or recipient. The minimum top-up is five US dollars, and any additional charge must be established by the challenge itself rather than inferred from this help text. Model-provider usage remains separately billed by that provider.
+
+## Output and next step
+On success, human output names the credited amount, payment rail, and available Vidbyte API balance. JSON and JSONL output contain the corresponding typed result fields. The command does not start or resume the failed agent operation. Verify that the available balance covers the original or remaining operation, then retry or resume it explicitly and preserve its original idempotency key when one was supplied.
+
+## Related commands
+Use `vidbyte-cli agents` or the relevant research command only after the balance is confirmed. The original operation may have made progress before a mid-run exhaustion error, so inspect its status before deciding whether to resume or repeat it. For browser-based account management, use the API settings URL above. Do not rerun a top-up with a new key merely because the first response was lost.

vidbyte_cli/commands/billing/top_up.py

@@ -0,0 +1,65 @@
+"""Explicitly pay the Vidbyte API-balance top-up challenge."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+import click
+
+from ...lib.api.endpoints.billing import TOP_UP_CENTS
+from ...lib.errors.failures import BillingTopUpApprovalRequired
+from ...lib.output import OutputDocument
+from .prompts.library import BillingHelpLibrary
+
+if TYPE_CHECKING:
+    from ...lib.runtime.context import ApplicationContext
+
+_TOP_UP_HELP = BillingHelpLibrary().load("top_up")
+_CONFIRM_HELP = BillingHelpLibrary().load("confirm")
+_IDEMPOTENCY_KEY_HELP = BillingHelpLibrary().load("idempotency_key")
+
+
+class BillingTopUpCommand:
+    """Registers the one explicit command that can purchase API balance."""
+
+    def register(self, parent: click.Group) -> None:
+        # Keeps payment behind an explicit confirmation flag and never runs from error handling.
+        @parent.command(name="top-up", help=_TOP_UP_HELP)
+        @click.option(
+            "--confirm",
+            is_flag=True,
+            help=_CONFIRM_HELP,
+        )
+        @click.option(
+            "--idempotency-key",
+            default=None,
+            help=_IDEMPOTENCY_KEY_HELP,
+        )
+        @click.pass_obj
+        def _run(context: ApplicationContext, confirm: bool, idempotency_key: str | None) -> None:
+            # Routes parsed Click options through the typed command boundary.
+            self.execute(context, confirm, idempotency_key)
+
+    def execute(
+        self, context: ApplicationContext, confirm: bool, idempotency_key: str | None
+    ) -> None:
+        # Validates approval before resolving credentials or creating a payment authorization.
+        if not confirm:
+            raise BillingTopUpApprovalRequired()
+        from ...lib.api.runtime_payment import RuntimePayment
+
+        payer = RuntimePayment(context.environment, TOP_UP_CENTS)
+        result = context.billing_endpoints().top_up(idempotency_key or str(uuid4()), payer)
+        context.output().result(
+            OutputDocument(kind="billing.top_up", data=result.model_dump(mode="json")),
+            self._summary(result.credited_cents, result.available_balance_cents, result.rail),
+        )
+
+    @staticmethod
+    def _summary(credited_cents: int, available_balance_cents: int, rail: str) -> str:
+        # Reports only non-secret financial outcome fields returned by the backend.
+        return (
+            f"Added ${credited_cents / 100:.2f} to Vidbyte API balance via {rail}. "
+            f"Available balance: ${available_balance_cents / 100:.2f}."
+        )