valkyrie-cli 2026.11.9__py3-none-any.whl

valkyrie/cli/dataset.py

@@ -0,0 +1,182 @@
+from pathlib import Path
+
+import click
+
+from valkyrie.cli.client import call
+from valkyrie.cli.display import format_option, format_table, local_time, one_line
+from valkyrie.cli.resource import (
+    INCLUDE_ARCHIVED,
+    RESOURCE_NAME,
+    TASK_ID,
+    list_resources,
+    show_resource,
+)
+
+
+@click.group(help="Create, list, show, update and remove the datasets that belong to your benchmarks.")
+def dataset() -> None:
+    pass
+
+
+@dataset.command(
+    name="create",
+    help=(
+        "Create a dataset in a benchmark.\n\n"
+        "BENCHMARK is a benchmark you created with `valkyrie benchmark create`. NAME is lowercase letters and "
+        "digits with single '.', '_' or '-' separators, such as verified.\n\n"
+        "Example:\n"
+        '    valkyrie dataset create swe-bench verified --description "Human-verified issues"'
+    ),
+)
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("name", metavar="NAME", type=RESOURCE_NAME)
+@click.option("--description", default="", help="What the dataset holds.")
+def create_dataset(benchmark: str, name: str, description: str) -> None:
+    created = call(lambda client: client.datasets.create(benchmark, name, description=description))
+    click.echo(
+        click.style(f"✓ Dataset created: {one_line(created.benchmark)}/{one_line(created.name)}", fg="green", bold=True)
+    )
+
+
+@dataset.command(name="list", help="List the datasets in a benchmark.")
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@INCLUDE_ARCHIVED
+@format_option()
+def list_datasets(benchmark: str, include_archived: bool, output_format: str) -> None:
+    response = call(lambda client: client.datasets.list(benchmark, include_archived=include_archived))
+    list_resources(response, response.datasets, output_format, "dataset")
+
+
+@dataset.command(name="show", help="Show one dataset, archived or not.")
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("name", metavar="NAME", type=RESOURCE_NAME)
+@format_option()
+def show_dataset(benchmark: str, name: str, output_format: str) -> None:
+    found = call(lambda client: client.datasets.get(benchmark, name))
+    show_resource(found, output_format, f"Benchmark:   {one_line(found.benchmark)}")
+
+
+@dataset.command(
+    name="update",
+    help=(
+        "Change a dataset's description. Its name never changes.\n\n"
+        "Example:\n"
+        '    valkyrie dataset update swe-bench verified --description "SWE-bench Verified"'
+    ),
+)
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("name", metavar="NAME", type=RESOURCE_NAME)
+@click.option("--description", required=True, help="The description the dataset now has.")
+def update_dataset(benchmark: str, name: str, description: str) -> None:
+    updated = call(lambda client: client.datasets.update(benchmark, name, description=description))
+    click.echo(
+        click.style(f"✓ Dataset updated: {one_line(updated.benchmark)}/{one_line(updated.name)}", fg="green", bold=True)
+    )
+
+
+@dataset.command(
+    name="remove",
+    help="Archive a dataset. It stays readable, keeps its name, and can be restored.",
+)
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("name", metavar="NAME", type=RESOURCE_NAME)
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
+def remove_dataset(benchmark: str, name: str, yes: bool) -> None:
+    if not yes and not click.confirm(f"Archive dataset '{benchmark}/{name}'?"):
+        click.echo("Cancelled.")
+        return
+    call(lambda client: client.datasets.remove(benchmark, name))
+    click.echo(click.style(f"✓ Dataset '{benchmark}/{name}' archived.", fg="green", bold=True))
+
+
+@dataset.command(name="restore", help="Restore an archived dataset so its tasks can change again.")
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("name", metavar="NAME", type=RESOURCE_NAME)
+def restore_dataset(benchmark: str, name: str) -> None:
+    restored = call(lambda client: client.datasets.restore(benchmark, name))
+    click.echo(
+        click.style(
+            f"✓ Dataset restored: {one_line(restored.benchmark)}/{one_line(restored.name)}", fg="green", bold=True
+        )
+    )
+
+
+@dataset.group(name="task", help="Store, list, download and remove the task archives of a dataset.")
+def task() -> None:
+    pass
+
+
+@task.command(
+    name="put",
+    help=(
+        "Store a task's .zip archive in a dataset, replacing the task if it exists.\n\n"
+        "TASK_ID starts with a letter or digit and uses letters, digits, '.', '_' and '-'.\n\n"
+        "Example:\n"
+        "    valkyrie dataset task put swe-bench verified django__django-11099 ./django__django-11099.zip"
+    ),
+)
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("dataset_name", metavar="DATASET", type=RESOURCE_NAME)
+@click.argument("task_id", metavar="TASK_ID", type=TASK_ID)
+@click.argument("archive", metavar="ARCHIVE", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+def put_task(benchmark: str, dataset_name: str, task_id: str, archive: Path) -> None:
+    stored = call(lambda client: client.datasets.tasks.put(benchmark, dataset_name, task_id, archive))
+    click.echo(
+        click.style(
+            f"✓ Task stored: {benchmark}/{dataset_name}/{one_line(stored.task_id)} ({stored.size:,} bytes)",
+            fg="green",
+            bold=True,
+        )
+    )
+
+
+@task.command(name="list", help="List the tasks stored in a dataset.")
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("dataset_name", metavar="DATASET", type=RESOURCE_NAME)
+@format_option()
+def list_tasks(benchmark: str, dataset_name: str, output_format: str) -> None:
+    response = call(lambda client: client.datasets.tasks.list_all(benchmark, dataset_name))
+    if output_format == "json":
+        click.echo(response.model_dump_json())
+        return
+    format_table(
+        [
+            {
+                "Task": one_line(entry.task_id),
+                "Bytes": f"{entry.size:,}",
+                "Updated": local_time(entry.last_modified) if entry.last_modified else "",
+            }
+            for entry in response.tasks
+        ],
+        ["Task", "Bytes", "Updated"],
+        item_name="task",
+    )
+
+
+@task.command(name="download", help="Download a task's archive. It is saved as TASK_ID.zip unless you pass --output.")
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("dataset_name", metavar="DATASET", type=RESOURCE_NAME)
+@click.argument("task_id", metavar="TASK_ID", type=TASK_ID)
+@click.option("--output", "-o", type=click.Path(dir_okay=False, path_type=Path), help="Where to save the archive.")
+@click.option("--overwrite", is_flag=True, help="Replace the file if it exists.")
+def download_task(benchmark: str, dataset_name: str, task_id: str, output: Path | None, overwrite: bool) -> None:
+    destination = output or Path(f"{task_id}.zip")
+    saved = call(
+        lambda client: client.datasets.tasks.download(
+            benchmark, dataset_name, task_id, destination, overwrite=overwrite
+        )
+    )
+    click.echo(click.style(f"✓ Task downloaded: {saved}", fg="green", bold=True))
+
+
+@task.command(name="remove", help="Delete a task's archive from a dataset.")
+@click.argument("benchmark", metavar="BENCHMARK", type=RESOURCE_NAME)
+@click.argument("dataset_name", metavar="DATASET", type=RESOURCE_NAME)
+@click.argument("task_id", metavar="TASK_ID", type=TASK_ID)
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
+def remove_task(benchmark: str, dataset_name: str, task_id: str, yes: bool) -> None:
+    if not yes and not click.confirm(f"Delete task '{benchmark}/{dataset_name}/{task_id}'?"):
+        click.echo("Cancelled.")
+        return
+    call(lambda client: client.datasets.tasks.remove(benchmark, dataset_name, task_id))
+    click.echo(click.style(f"✓ Task '{benchmark}/{dataset_name}/{task_id}' removed.", fg="green", bold=True))

valkyrie/cli/display.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from datetime import datetime, timezone
+from typing import TypeVar
+
+import click
+from click.decorators import FC
+
+from valkyrie.display import terminal_safe
+
+Page = TypeVar("Page")
+
+
+def format_option(help: str = "Output format.", choices: Sequence[str] = ("text", "json")) -> Callable[[FC], FC]:
+    return click.option(
+        "--format",
+        "output_format",
+        type=click.Choice(list(choices), case_sensitive=False),
+        default="text",
+        show_default=True,
+        help=help,
+    )
+
+
+def one_line(value: str) -> str:
+    return terminal_safe(value, preserve_newlines=False)
+
+
+def status_label(value: str) -> str:
+    return value.replace("_", " ").title()
+
+
+def compact_json(payload: Mapping[str, object]) -> str:
+    return json.dumps(payload, allow_nan=False, sort_keys=True, separators=(",", ":"))
+
+
+def utc_isoformat(value: datetime | None = None) -> str:
+    value = value or datetime.now(timezone.utc)
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def progress_percent(finished_tasks: int, total_tasks: int) -> float:
+    return finished_tasks / total_tasks * 100 if total_tasks > 0 else 0
+
+
+def local_time(dt: datetime) -> str:
+    return dt.astimezone().strftime("%Y-%m-%d %H:%M:%S %Z")
+
+
+def short_local_time(dt: datetime, include_date: bool = True) -> str:
+    fmt = "%m/%d %H:%M" if include_date else "%H:%M"
+    return dt.astimezone().strftime(fmt)
+
+
+def format_table(
+    rows: list[dict[str, str]],
+    headers: list[str],
+    current_page: int = 1,
+    total_pages: int = 1,
+    total_count: int | None = None,
+    item_name: str = "item",
+) -> None:
+    if not rows:
+        click.echo(click.style(f"No {item_name}s found.", fg="yellow"))
+        return
+
+    if total_count is None:
+        total_count = len(rows)
+
+    column_widths = {}
+    for header in headers:
+        max_width = len(header)
+        for row in rows:
+            value = str(row.get(header, ""))
+            clean_value = click.unstyle(value)
+            max_width = max(max_width, len(clean_value))
+        column_widths[header] = max_width
+
+    header_line = "  ".join(f"{header:<{column_widths[header]}}" for header in headers)
+    separator = "─" * len(header_line)
+
+    click.echo()
+    click.echo(click.style(header_line, bold=True))
+    click.echo(separator)
+
+    for row in rows:
+        cells: list[str] = []
+        for header in headers:
+            value = str(row.get(header, ""))
+            clean_value = click.unstyle(value)
+            padding = column_widths[header] - len(clean_value)
+            cells.append(f"{value}{' ' * padding}")
+        click.echo("  ".join(cells))
+
+    click.echo(separator)
+
+    total_text = f"Total: {total_count} {item_name}(s)"
+    if total_pages > 1 and not _interactive_terminal():
+        click.echo(f"{total_text}, page {current_page}/{total_pages} (paging needs a terminal)")
+    elif total_pages > 1:
+        nav_text_raw = f"[h] ← prev  {current_page}/{total_pages}  next → [l]  [q] quit"
+        nav_text = click.style(nav_text_raw, fg="bright_black")
+        padding = len(separator) - len(total_text) - len(nav_text_raw)
+        click.echo(f"{total_text}{' ' * padding}{nav_text}")
+    else:
+        click.echo(total_text)
+
+
+def _interactive_terminal() -> bool:
+    return all(stream is not None and stream.isatty() for stream in (sys.stdin, sys.stdout))
+
+
+def _clear_pager() -> None:
+    click.echo("\033[2J\033[3J\033[1;1H", nl=False, color=True)
+
+
+def paginate_cli_pages(
+    load_page: Callable[[int, int], tuple[int, Page]],
+    render_page: Callable[[Page, int, int, int], None],
+    *,
+    limit: int,
+    render_empty: Callable[[], None],
+) -> None:
+    current_page = 1
+    interactive = _interactive_terminal()
+
+    while True:
+        total_count, page = load_page((current_page - 1) * limit, limit)
+        total_pages = max(1, (total_count + limit - 1) // limit)
+        if current_page > total_pages:
+            current_page = total_pages
+            continue
+
+        if interactive:
+            _clear_pager()
+
+        if total_count == 0:
+            render_empty()
+            break
+
+        render_page(page, current_page, total_pages, total_count)
+
+        if total_pages <= 1 or not interactive:
+            break
+
+        char = click.getchar()
+
+        if char == "l" and current_page < total_pages:
+            current_page += 1
+        elif char == "h" and current_page > 1:
+            current_page -= 1
+        elif char == "q" or char == "\x03":
+            break

valkyrie/cli/entry.py

@@ -0,0 +1,12 @@
+import os
+import sys
+
+
+def main():
+    os.environ.setdefault("PYDANTIC_DISABLE_PLUGINS", "__all__")
+    try:
+        from valkyrie.cli.main import cli
+
+        cli()
+    except KeyboardInterrupt:
+        sys.exit(130)

valkyrie/cli/lazy.py

@@ -0,0 +1,38 @@
+from collections.abc import Mapping
+from importlib import import_module
+from typing import Any
+
+import click
+from click.utils import make_default_short_help
+
+
+class LazyGroup(click.Group):
+    def __init__(
+        self,
+        *args: Any,
+        lazy_commands: Mapping[str, tuple[str, str]],
+        hidden_commands: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.lazy_commands = dict(lazy_commands)
+        self.hidden_commands = dict(hidden_commands or {})
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return sorted(self.lazy_commands)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        if cmd_name in self.lazy_commands:
+            target = self.lazy_commands[cmd_name][0]
+        elif cmd_name in self.hidden_commands:
+            target = self.hidden_commands[cmd_name]
+        else:
+            return None
+        module, attribute = target.split(":")
+        return getattr(import_module(module), attribute)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        names = self.list_commands(ctx)
+        limit = formatter.width - 6 - max(map(len, names))
+        with formatter.section("Commands"):
+            formatter.write_dl([(name, make_default_short_help(self.lazy_commands[name][1], limit)) for name in names])

valkyrie/cli/logging.py

@@ -0,0 +1,20 @@
+import logging
+import os
+
+from dotenv import load_dotenv
+
+CLI_LOGS_ENV_VAR = "VALKYRIE_CLI_LOGS"
+
+
+def configure_cli_logging() -> None:
+    if os.environ.get(CLI_LOGS_ENV_VAR) == "true":
+        logging.disable(logging.NOTSET)
+        return
+
+    logging.disable(logging.CRITICAL)
+
+
+def load_cli_environment() -> None:
+    configure_cli_logging()
+    load_dotenv()
+    configure_cli_logging()

valkyrie/cli/login.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import click
+
+from valkyrie.cli.client import call
+from valkyrie.cli.display import utc_isoformat
+from valkyrie.sdk import (
+    IdentityResponse,
+    LoginSession,
+    OrganizationsResponse,
+    SessionAuth,
+    ValkyrieAPIError,
+    ValkyrieClient,
+    ValkyrieConfig,
+    ValkyrieTransportError,
+    device_login,
+)
+
+
+def show_organizations(listing: OrganizationsResponse) -> None:
+    if not listing.organizations and not listing.invitations:
+        click.echo(
+            "You're not in an organization yet. Ask Vals AI to add you, "
+            "or ask an organization admin to run `valkyrie org invite EMAIL`."
+        )
+    for entry in listing.organizations:
+        click.echo(f"{'*' if entry.current else ' '} {entry.id}{' (admin)' if entry.admin else ''}")
+    for organization in listing.invitations:
+        click.echo(f"  {organization} (invited; run `valkyrie org accept {organization}`)")
+
+
+async def _organizations_or_identity(client: ValkyrieClient) -> OrganizationsResponse | IdentityResponse:
+    try:
+        return await client.account.organizations()
+    except ValkyrieAPIError as error:
+        if error.status_code != 404:
+            raise
+    return await client.account.identity()
+
+
+@click.command(help="Sign in with your browser, save the login, and use this Tracker by default.")
+@click.option("--no-browser", is_flag=True, help="Print the sign-in link without opening a browser.")
+def login(no_browser: bool) -> None:
+    tracker_url = ValkyrieConfig().url
+
+    def announce(link: str, user_code: str) -> None:
+        click.echo(f"Open {link} and confirm the code {user_code}.", err=True)
+        if not no_browser:
+            click.launch(link)
+
+    try:
+        session = device_login(tracker_url, announce)
+    except ValkyrieTransportError as error:
+        raise click.ClickException(str(error)) from error
+    session.save()
+    session.remember()
+    if ValkyrieConfig().api_key:
+        click.echo("VALKYRIE_API_KEY is set and takes precedence over this login; unset it to use the login.", err=True)
+    listing = call(_organizations_or_identity, auth=SessionAuth(session))
+    if isinstance(listing, IdentityResponse):
+        who = listing.email or listing.name or "your account"
+        click.echo(f"Logged in to {session.tracker_url} as {who} for {listing.organization}.")
+        return
+    click.echo(f"Logged in to {session.tracker_url} as {listing.email or 'your account'}.")
+    show_organizations(listing)
+
+
+@click.command(help="Forget the saved login for this Tracker, and stop using it by default.")
+def logout() -> None:
+    tracker_url = ValkyrieConfig().url
+    if LoginSession.forget(tracker_url):
+        click.echo(f"Logged out of {tracker_url}.")
+    else:
+        click.echo(f"You were not logged in to {tracker_url}.")
+
+
+@click.command(help="Show which Tracker, organization and account your requests use.")
+def whoami() -> None:
+    identity = call(lambda client: client.account.identity())
+    credential = {"login": "a login", "access_key": "an access key"}.get(identity.credential, "no credential")
+    who = identity.email or identity.name or "unknown user"
+    click.echo(f"{who} in {identity.organization} on {ValkyrieConfig().url} (using {credential})")
+
+
+@click.group(help="Create and revoke access keys for CI and other headless use.")
+def token() -> None:
+    pass
+
+
+@token.command(
+    "create", help="Create an access key for your organization. Set it as VALKYRIE_API_KEY where you need it."
+)
+@click.argument("name")
+@click.option(
+    "--expires-in-days",
+    type=click.IntRange(1, 90),
+    default=30,
+    show_default=True,
+    help="Days until the key stops working.",
+)
+def token_create(name: str, expires_in_days: int) -> None:
+    created = call(lambda client: client.account.create_access_key(name, expires_in_days=expires_in_days))
+    click.echo(f"Created access key {created.key_id}, expiring {utc_isoformat(created.expires_at)}.", err=True)
+    click.echo("It is shown only once:", err=True)
+    click.echo(created.key)
+
+
+@token.command(
+    "revoke",
+    help="Delete an access key you created. The Tracker may accept it for up to one more minute, and tokens exchanged from it until they expire.",
+)
+@click.argument("key_id")
+def token_revoke(key_id: str) -> None:
+    call(lambda client: client.account.revoke_access_key(key_id))
+    click.echo(f"Revoked access key {key_id}.")

valkyrie/cli/main.py

@@ -0,0 +1,62 @@
+import sys
+from typing import Any
+
+import click
+
+from valkyrie.cli.entry import main
+from valkyrie.cli.lazy import LazyGroup
+from valkyrie.cli.logging import load_cli_environment
+
+
+class _ValkyrieCLI(LazyGroup):
+    def invoke(self, ctx: click.Context) -> Any:
+        try:
+            return super().invoke(ctx)
+        except Exception as error:
+            errors = sys.modules.get("valkyrie.sdk.errors")
+            if errors is not None and isinstance(error, errors.ValkyrieConfigError):
+                raise click.ClickException(str(error)) from error
+            raise
+
+
+@click.group(
+    cls=_ValkyrieCLI,
+    lazy_commands={
+        "run": ("valkyrie.cli.run:run", "Start, monitor, manage, and retrieve runs."),
+        "agent": ("valkyrie.cli.agent:agent", "Install, upload, list, download, and remove agents."),
+        "benchmark": (
+            "valkyrie.cli.benchmark:benchmark",
+            "Export the task IDs in a benchmark dataset, and save benchmark services.",
+        ),
+        "queue": ("valkyrie.cli.queue:queue", "Inspect your organization's sandbox scheduler."),
+        "project": ("valkyrie.cli.project:project", "Manage the projects runs are started in."),
+        "secret": ("valkyrie.cli.secret:secret", "Store secrets that your runs reference."),
+        "provider": (
+            "valkyrie.cli.provider:provider",
+            "Choose the secret that configures each sandbox provider, and your default provider.",
+        ),
+        "login": (
+            "valkyrie.cli.login:login",
+            "Sign in with your browser, save the login, and use this Tracker by default.",
+        ),
+        "logout": (
+            "valkyrie.cli.login:logout",
+            "Forget the saved login for this Tracker, and stop using it by default.",
+        ),
+        "whoami": ("valkyrie.cli.login:whoami", "Show which Tracker, organization and account your requests use."),
+        "token": ("valkyrie.cli.login:token", "Create and revoke access keys for CI and other headless use."),
+        "org": ("valkyrie.cli.org:org", "Create, join and switch organizations, and manage their members."),
+        "ui": ("valkyrie.cli.ui:ui", "Browse runs, tasks and logs in a terminal UI."),
+    },
+    hidden_commands={"dataset": "valkyrie.cli.dataset:dataset"},
+    help="Run agents against benchmarks and manage their runs.",
+)
+def cli():
+    load_cli_environment()
+
+
+__all__ = ["cli"]
+
+
+if __name__ == "__main__":
+    main()