elan-cli 0.1.0__py3-none-any.whl

elan_cli/main.py

@@ -0,0 +1,664 @@
+"""`elan` — the command line a developer deploys an agent with.
+
+WHAT IS HERE IS WHAT WORKS. The plan lists a longer command set, and the ones
+that need a service route nobody has built are ABSENT rather than stubbed. A
+subcommand that parses its arguments, prints "not implemented" and exits 0 is
+worse than no subcommand: it is discoverable in `--help`, it looks supported,
+and somebody writes it into a script.
+
+Still missing, and each for a stated reason rather than an oversight:
+
+    `budget`   the ledger's per-invocation gate is vestigial under BYOK
+               (ADR-0063); there is nothing honest to report yet.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from elan_cli import adk as adk_cmd
+from elan_cli import (
+    auth,
+    deploy,
+    env,
+    files,
+    rollback,
+    scaffold,
+    secret,
+    tenant,
+    validate,
+    wallet,
+)
+from elan_cli import destroy as destroy_cmd
+from elan_cli import doctor as doctor_cmd
+from elan_cli import invoke as invoke_cmd
+from elan_cli import logs as logs_cmd
+from elan_cli import projects as projects_cmd
+from elan_cli.auth import AuthError
+from elan_cli.client import Api, ApiError
+from elan_cli.config import Config, ConfigError
+from elan_cli.files import FilesError  # noqa: F401 — re-exported for tests
+from elan_cli.project import ProjectError, find
+from elan_cli.secret import SecretError
+from elan_cli.wallet import WalletError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="elan", description="Deploy an ADK agent to the platform.")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    login = sub.add_parser("login", help="sign in with a browser, on any machine")
+    login.add_argument("--api", default="",
+                       help="the platform's URL. Needed once; remembered "
+                            "afterwards. Everything else about signing in is "
+                            "asked of the platform rather than configured.")
+    sub.add_parser("logout", help="forget the stored refresh token")
+    sub.add_parser("whoami", help="who the stored credential says you are")
+
+    init = sub.add_parser("init", help="create elan.yaml and its directories")
+    init.add_argument("--tenant", required=True)
+    init.add_argument("--project", required=True)
+    init.add_argument("--repo", default="https://github.com/ORG/REPO")
+    init.add_argument("--directory", type=Path, default=None)
+    init.add_argument("--agent", default="hello-agent",
+                      help="the first agent's slug; a project with none does "
+                           "not validate, so one is always created")
+    # NO `--runtime`. It named a checkout of the platform repository, because
+    # the agentkit packages were published to no index; they are on PyPI now,
+    # so `init` builds the .venv unconditionally and has nothing to ask for
+    # (ADR-0220).
+
+    new = sub.add_parser("new", help="scaffold a target and declare it")
+    new.add_argument("kind", choices=sorted(scaffold.KINDS))
+    new.add_argument("slug")
+
+    # `parse_known_args` IS NOT USED and REMAINDER is, because every option
+    # after `adk` belongs to ADK. argparse would otherwise claim `--port` and
+    # refuse it as unknown, which reads as elan not supporting something ADK
+    # documents.
+    passthrough = sub.add_parser(
+        "adk", help="run ADK's own tools against this repo (web, run, eval)")
+    passthrough.add_argument("args", nargs=argparse.REMAINDER,
+                             help="Passed to ADK unchanged.")
+
+    # `env` TAKES NOTHING, for the same reason `init` lost its flag: the
+    # runtime resolves from the index by name.
+    sub.add_parser(
+        "env", help="create the local environment `elan validate` needs")
+
+    check = sub.add_parser("validate",
+                           help="check both files against each other")
+    check.add_argument("--python", default=None, metavar="PATH",
+                       help="Interpreter to read your agents with. Defaults "
+                            "to an activated virtualenv, then a .venv beside "
+                            "elan.yaml. It needs the platform runtime "
+                            "installed, which the CLI's own environment "
+                            "deliberately does not have.")
+
+    back = sub.add_parser("rollback",
+                          help="put this project back to a previous deploy")
+    back.add_argument("to_deployment_id",
+                      help="the deployment to restore, from `elan status` or "
+                           "the console. Not a digest and not a ref: a digest "
+                           "names one image and a project has several, and a "
+                           "ref names a commit that may have been "
+                           "force-pushed away.")
+    back.add_argument("--yes", action="store_true",
+                      help="skip the confirmation")
+    back.add_argument("--no-wait", action="store_true")
+
+    gone = sub.add_parser("destroy",
+                          help="remove an agent or a project and its resources")
+    gone.add_argument("agent", nargs="?", default="",
+                      help="the agent to remove; omit with --project")
+    gone.add_argument("--project", action="store_true",
+                      help="remove the whole project, every agent in it")
+    gone.add_argument("--yes", action="store_true", help="skip the confirmation")
+
+    sub.add_parser("doctor",
+                   help="check the platform's record against what exists")
+
+    send = sub.add_parser("invoke", help="send an agent a message")
+    send.add_argument("target", help="the agent's slug")
+    send.add_argument("--text", required=True)
+    send.add_argument("--session", default="",
+                      help="continue a conversation instead of starting one")
+    send.add_argument("--timeout", type=float,
+                      default=invoke_cmd.DEFAULT_TIMEOUT,
+                      help="seconds to wait for a reply (default 300; a "
+                           "sleeping agent has to be scheduled and started "
+                           "before it reads its queue)")
+
+    log = sub.add_parser("logs", help="a build's output, or a workload's")
+    # OPTIONAL, BECAUSE `--workload` REPLACES IT. argparse cannot express "one of
+    # these two" in a way that reads well in `--help`, so the check is in the
+    # dispatch and the error names both forms.
+    log.add_argument("deployment_id", nargs="?", default="",
+                     help="a deployment id, for a BUILD log")
+    log.add_argument("--workload", default="",
+                     help="a workload name, for what it is saying NOW")
+    log.add_argument("--project", default="",
+                     help="which project the workload is in (required with "
+                          "--workload: a workload name is unique within a "
+                          "project, not within a tenant)")
+    log.add_argument("--since", type=int, default=60, metavar="MINUTES",
+                     help="how far back to read a workload's log (default 60)")
+    log.add_argument("--probes", action="store_true",
+                     help="include health-check requests, which are most of an "
+                          "idle pod's output and are hidden by default")
+    log.add_argument("--tail", nargs="?", type=int, const=logs_cmd.DEFAULT_TAIL,
+                     default=0, help="only the last lines (default 50)")
+
+    projects = sub.add_parser("projects", help="this tenant's projects")
+    projects_sub = projects.add_subparsers(dest="projects_command")
+    projects_sub.add_parser("ls", help="list them")
+    made = projects_sub.add_parser("create", help="register a new one")
+    made.add_argument("slug")
+    made.add_argument("--name", default="")
+    made.add_argument("--repo", default="")
+
+    agents = sub.add_parser("agents", help="what each agent is running")
+    agents.add_argument("--project", default="",
+                        help="defaults to every project of this tenant")
+
+    deploy_cmd = sub.add_parser("deploy", help="build and roll out this project")
+    deploy_cmd.add_argument("--ref", default="HEAD",
+                            help="branch, tag or sha; resolved and written "
+                                 "into elan.yaml before submitting")
+    deploy_cmd.add_argument("--no-wait", action="store_true",
+                            help="submit and return the id")
+
+    status = sub.add_parser("status", help="how a deployment is getting on")
+    status.add_argument("deployment_id")
+
+    # PLATFORM STAFF ONLY, enforced by the service rather than here. A CLI that
+    # refused locally would be a second rule to keep in step with the one that
+    # actually holds the credential.
+    tenant_cmd = sub.add_parser("tenant", help="create and list tenants (platform staff)")
+    tenant_sub = tenant_cmd.add_subparsers(dest="tenant_command")
+    tenant_create = tenant_sub.add_parser("create", help="create a customer")
+    tenant_create.add_argument("slug")
+    tenant_create.add_argument("--name", default="",
+                               help="what a human sees; defaults to the slug")
+    tenant_sub.add_parser("ls", help="every tenant")
+
+    secret_cmd = sub.add_parser("secret", help="your own credentials")
+    secret_sub = secret_cmd.add_subparsers(dest="secret_command")
+    secret_set = secret_sub.add_parser("set", help="set or rotate a value")
+    secret_set.add_argument("kind", choices=secret.KINDS)
+    secret_set.add_argument("name")
+    # NOT `--value`. A secret on the command line is a secret in the shell
+    # history of everyone who runs it.
+    secret_set.add_argument("--from-file", default="-", metavar="PATH",
+                            help="file holding the value, or - for stdin "
+                                 "(the default)")
+    secret_sub.add_parser("ls", help="which secrets are set (names only)")
+    secret_rm = secret_sub.add_parser("rm", help="remove a secret entirely")
+    secret_rm.add_argument("kind", choices=secret.KINDS)
+    secret_rm.add_argument("name")
+
+    # ── FILES AN AGENT READS AND WRITES ────────────────────────────────────
+    #
+    # THE SCOPE IS IN THE FILENAME AND NOT IN A FLAG, because that is how a
+    # tool addresses it: `project:policy.md` from here is the same name
+    # `tool_context.load_artifact` takes. A `--scope` flag would be a second
+    # way to say the same thing, and the two would disagree.
+    files_cmd = sub.add_parser(
+        "files", help="artifacts an agent reads and writes")
+    files_scope = argparse.ArgumentParser(add_help=False)
+    files_scope.add_argument(
+        "--project", default="",
+        help="defaults to the project of the elan.yaml you are standing in")
+    files_scope.add_argument(
+        "target", help="the agent or workflow slug")
+    files_scope.add_argument(
+        "--user", default="",
+        help="one of YOUR end users, for a file that is theirs")
+    files_sub = files_cmd.add_subparsers(dest="files_command")
+
+    files_ls = files_sub.add_parser(
+        "ls", parents=[files_scope], help="what this conversation can see")
+    files_ls.add_argument("--session", default="", help="the session id")
+
+    files_get = files_sub.add_parser(
+        "get", parents=[files_scope], help="download one file")
+    files_get.add_argument("filename", help="e.g. report.pdf or project:policy.md")
+    files_get.add_argument("--session", default="")
+    files_get.add_argument("--version", type=int, help="defaults to the newest")
+    files_get.add_argument("-o", "--out", default="", help="where to write it")
+
+    files_put = files_sub.add_parser(
+        "put", parents=[files_scope], help="upload one file")
+    files_put.add_argument("path", help="the local file")
+    files_put.add_argument(
+        "--name", default="",
+        help="the artifact name, which chooses the scope. Defaults to the "
+             "file's own name, i.e. this conversation's scope. Prefix with "
+             "`project:` or `agent:` for a shared document (admin only).")
+    files_put.add_argument("--session", default="")
+    files_put.add_argument("--content-type", default="application/octet-stream",
+                           help="signed into the URL; a later read reports it")
+
+    files_rm = files_sub.add_parser(
+        "rm", parents=[files_scope], help="remove one file and every version")
+    files_rm.add_argument("filename")
+    files_rm.add_argument("--session", default="")
+
+    # ── YOUR OWN END USERS' CREDIT ──────────────────────────────────────────
+    #
+    # NO `--tenant` ANYWHERE BELOW. Every route derives it from the verified
+    # token, so a flag would name a value the service ignores — and a flag that
+    # does nothing is worse than no flag.
+    wallet_cmd = sub.add_parser(
+        "wallet", help="credit you hold for your own end users")
+    # ONE `--project` FOR EVERY SUBCOMMAND, declared on a shared parent rather
+    # than repeated eight times — repeated flags are how one of them comes to
+    # differ.
+    wallet_scope = argparse.ArgumentParser(add_help=False)
+    wallet_scope.add_argument(
+        "--project", default="",
+        help="defaults to the project of the elan.yaml you are standing in")
+    wallet_sub = wallet_cmd.add_subparsers(dest="wallet_command")
+
+    wallet_ls = wallet_sub.add_parser(
+        "ls", parents=[wallet_scope], help="your users and what they have")
+    wallet_ls.add_argument("--limit", type=int, default=50)
+
+    wallet_show = wallet_sub.add_parser(
+        "show", parents=[wallet_scope], help="one user's balance")
+    wallet_show.add_argument("user")
+
+    wallet_new = wallet_sub.add_parser(
+        "create", parents=[wallet_scope], help="make a wallet for one of your users")
+    wallet_new.add_argument("user")
+    wallet_new.add_argument("--label", default="", help="for you, reading a list")
+
+    # DOLLARS POSITIONALLY, `--micros` FOR A CALLER THAT ALREADY HAS THE INTEGER.
+    # A person types `5`; a script that read a balance back should not have to
+    # divide by a million to pass it on.
+    wallet_add = wallet_sub.add_parser(
+        "credit", parents=[wallet_scope], help="add credit, in dollars")
+    wallet_add.add_argument("user")
+    wallet_add.add_argument("amount", nargs="?", help="in dollars, e.g. 5 or 2.50")
+    wallet_add.add_argument("--micros", type=int, help="in micro-USD instead")
+    wallet_add.add_argument("--ref", default="",
+                            help="why — it is what makes a double credit visible")
+
+    wallet_fix = wallet_sub.add_parser(
+        "adjust", parents=[wallet_scope], help="correct in either direction; negative claws back")
+    wallet_fix.add_argument("user")
+    wallet_fix.add_argument("amount", nargs="?", help="in dollars, e.g. -2.50")
+    wallet_fix.add_argument("--micros", type=int)
+    wallet_fix.add_argument("--ref", default="")
+
+    wallet_freeze = wallet_sub.add_parser(
+        "freeze", parents=[wallet_scope], help="stop this user spending, keeping their balance")
+    wallet_freeze.add_argument("user")
+    wallet_thaw = wallet_sub.add_parser(
+        "unfreeze", parents=[wallet_scope], help="let them spend again")
+    wallet_thaw.add_argument("user")
+
+    wallet_log = wallet_sub.add_parser(
+        "statement", parents=[wallet_scope], help="one user's movements, newest first")
+    wallet_log.add_argument("user")
+    wallet_log.add_argument("--limit", type=int, default=25)
+    return parser
+
+
+def run(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 2
+
+    try:
+        return _dispatch(args, parser)
+    except (ProjectError, ConfigError, AuthError, ApiError, SecretError,
+            WalletError) as exc:
+        # EVERY ONE OF THESE IS ALREADY PHRASED FOR THE DEVELOPER, and none is
+        # about this file. A traceback here would name the one place the
+        # problem is not.
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _dispatch(args, parser) -> int:
+    if args.command == "init":
+        return scaffold.init(args.directory or Path.cwd(), tenant=args.tenant,
+                             project=args.project, repo=args.repo,
+                             agent=args.agent)
+    if args.command == "new":
+        return scaffold.new(args.kind, args.slug)
+    if args.command == "adk":
+        return adk_cmd.run(args.args)
+
+    if args.command == "env":
+        return env.run()
+
+    if args.command == "validate":
+        return validate.run(python=args.python)
+
+    if args.command == "login":
+        return _login(_config_for_login(args.api))
+    if args.command == "logout":
+        config = Config.load()
+        if auth.forget(config.issuer):
+            print(f"signed out of {config.issuer}")
+        else:
+            print("not signed in")
+        return 0
+    if args.command == "whoami":
+        return _whoami(Config.load())
+
+    if args.command == "secret":
+        if not args.secret_command:
+            parser.parse_args(["secret", "--help"])
+            return 2
+        config = Config.load()
+        api = Api(config)
+        try:
+            if args.secret_command == "set":
+                return secret.set_(api, args.kind, args.name, args.from_file)
+            if args.secret_command == "rm":
+                return secret.rm(api, args.kind, args.name)
+            return secret.ls(api)
+        finally:
+            api.close()
+
+    if args.command == "files":
+        if not args.files_command:
+            parser.parse_args(["files", "--help"])
+            return 2
+        api = Api(Config.load())
+        try:
+            return {"ls": files.ls, "get": files.get,
+                    "put": files.put, "rm": files.rm}[args.files_command](args, api)
+        except (files.FilesError, ApiError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+
+    if args.command == "wallet":
+        if not args.wallet_command:
+            parser.parse_args(["wallet", "--help"])
+            return 2
+        config = Config.load()
+        api = Api(config)
+        try:
+            what = args.wallet_command
+            # RESOLVED ONCE, HERE. Every subcommand needs it and every one of
+            # them would otherwise have to remember to look it up.
+            project = wallet.project_of(args.project)
+            if what == "show":
+                return wallet.show(api, project, args.user)
+            if what == "create":
+                return wallet.create(api, project, args.user, args.label)
+            if what == "credit":
+                return wallet.credit(api, project, args.user, args.amount,
+                                     args.micros, args.ref)
+            if what == "adjust":
+                return wallet.adjust(api, project, args.user, args.amount,
+                                     args.micros, args.ref)
+            if what == "freeze":
+                return wallet.status(api, project, args.user, "frozen")
+            if what == "unfreeze":
+                return wallet.status(api, project, args.user, "active")
+            if what == "statement":
+                return wallet.statement(api, project, args.user, args.limit)
+            return wallet.ls(api, project, args.limit)
+        finally:
+            api.close()
+
+    if args.command == "tenant":
+        if not args.tenant_command:
+            parser.parse_args(["tenant", "--help"])
+            return 2
+        config = Config.load()
+        api = Api(config)
+        try:
+            if args.tenant_command == "create":
+                return tenant.create(api, args.slug, args.name)
+            return tenant.ls(api)
+        finally:
+            api.close()
+
+    if args.command == "projects":
+        if not args.projects_command:
+            parser.parse_args(["projects", "--help"])
+            return 2
+        config = Config.load()
+        api = Api(config)
+        try:
+            if args.projects_command == "create":
+                return projects_cmd.create(api, args.slug, args.name, args.repo)
+            return projects_cmd.ls(api)
+        finally:
+            api.close()
+
+    if args.command == "agents":
+        config = Config.load()
+        api = Api(config)
+        try:
+            return projects_cmd.agents(api, args.project)
+        finally:
+            api.close()
+
+    if args.command == "doctor":
+        config = Config.load()
+        api = Api(config)
+        try:
+            return doctor_cmd.run(api)
+        finally:
+            api.close()
+
+    if args.command == "destroy":
+        config = Config.load()
+        api = Api(config)
+        try:
+            return destroy_cmd.run(api, args.agent,
+                                   whole_project=args.project,
+                                   assume_yes=args.yes)
+        finally:
+            api.close()
+
+    if args.command == "invoke":
+        config = Config.load()
+        api = Api(config)
+        try:
+            # FROM elan.yaml, WHICH IS THE ONLY PLACE THAT KNOWS. `invoke` is
+            # run inside a project, and the deploy file names it — so this is
+            # read rather than asked for, the same way `deploy` reads it.
+            return invoke_cmd.run(api, args.target, args.text,
+                                  session=args.session,
+                                  project=_project_here(),
+                                  timeout=args.timeout)
+        finally:
+            api.close()
+
+    if args.command == "logs":
+        if bool(args.deployment_id) == bool(args.workload):
+            # BOTH OR NEITHER IS THE AMBIGUOUS CASE, and the two logs come from
+            # different places — a build that has finished, and a pod that is
+            # running. Guessing would print the wrong one convincingly.
+            print("Name one: `elan logs <deployment-id>` for a build, or "
+                  "`elan logs --workload <name> --project <slug>` for what a "
+                  "running workload is saying.", file=sys.stderr)
+            return 2
+        config = Config.load()
+        api = Api(config)
+        try:
+            if args.workload:
+                return logs_cmd.workload(
+                    api, args.workload, project=args.project,
+                    minutes=args.since, probes=args.probes, tail=args.tail)
+            return logs_cmd.run(api, args.deployment_id, tail=args.tail)
+        finally:
+            api.close()
+
+    if args.command == "rollback":
+        config = Config.load()
+        api = Api(config)
+        try:
+            return rollback.run(api, args.to_deployment_id,
+                                wait=not args.no_wait, assume_yes=args.yes)
+        finally:
+            api.close()
+
+    if args.command in ("deploy", "status"):
+        config = Config.load()
+        api = Api(config)
+        try:
+            if args.command == "deploy":
+                return deploy.run(api, ref=args.ref, wait=not args.no_wait)
+            return deploy.status(api, args.deployment_id)
+        finally:
+            api.close()
+
+    parser.print_help()
+    return 2
+
+
+def _config_for_login(api_override: str) -> Config:
+    """The platform's URL, then everything else FROM the platform.
+
+    `--api` is the one thing a developer can supply and the only thing they
+    should have to know. Asking them for an issuer, a client id and a generated
+    project id was the original design and it was wrong: those are the
+    platform's own facts, they are all public, and a tool that makes somebody
+    paste four of them has acquired a setup page.
+    """
+    if api_override:
+        config = Config(api=api_override.rstrip("/"))
+    else:
+        config = Config.load()
+
+    discovered = auth.platform_auth(config.api)
+    config = config.with_auth(discovered)
+    config.save()
+    return config
+
+
+def _project_here() -> str:
+    """The project named by the elan.yaml this command is being run inside.
+
+    THE ONLY PLACE THAT KNOWS. A topic is
+    `agent.invoke.<tenant>.<project>.<agent>` and ADK keys a session on
+    `<tenant>.<project>.<agent>`, so a command that does not send the project
+    is addressing the PLATFORM's own — which under a customer's tenant names
+    nothing at all.
+
+    EMPTY RATHER THAN AN ERROR WHEN THERE IS NO SPEC. `elan invoke` from
+    outside a project is how somebody pokes the platform's own canary, and
+    that really is `platform/canary` — which is exactly what the services
+    default to.
+    """
+    try:
+        return find().spec.project
+    except ProjectError:
+        return ""
+
+
+def _login(config: Config) -> int:
+    print(f"signing in to {config.api}")
+    device = auth.begin(config)
+
+    # OUR OWN PAGE, NOT THE ISSUER'S `verification_uri`.
+    #
+    # The issuer answers with a URL on `zitadel.<domain>` whatever the login-UI
+    # setting says. Following it sends a developer to a vendor's page on a
+    # hostname they never typed — and a security key enrolled there is bound to
+    # THAT origin, so the console can never assert it and the account is locked
+    # out of the console until an administrator deletes the factor. That
+    # happened twice here.
+    #
+    # FALLS BACK TO THE ISSUER'S when the platform did not name one, because a
+    # sign-in that works on the wrong page beats one that cannot start.
+    ours = config.device_url
+    complete = (f"{ours}?user_code={device['user_code']}" if ours
+                else device.get("verification_uri_complete"))
+
+    print("To sign in, open:\n")
+    print(f"  {complete or device['verification_uri']}\n")
+    if not complete:
+        print(f"and enter the code:  {device['user_code']}\n")
+    else:
+        # PRINTED ANYWAY. The complete URI carries the code, but a developer
+        # copying a long URL into a phone will often type the code instead —
+        # and being unable to find it at that point is a dead end.
+        print(f"(the code, if asked:  {device['user_code']})\n")
+    print("Waiting...")
+
+    tokens = auth.poll(config, device)
+    if not tokens.refresh_token:
+        # WORTH SAYING RATHER THAN SILENTLY DEGRADING. Without a refresh token
+        # every command in an hour needs a browser again, and the developer
+        # would blame the CLI rather than the missing `offline_access` grant.
+        print("\nwarning: the issuer returned no refresh token, so this "
+              "session cannot be renewed.\n         The CLI's application "
+              "needs the refresh_token grant.", file=sys.stderr)
+    else:
+        auth.store(config.issuer, tokens.refresh_token)
+        # AFTER `store`, WHICH CLEARS THE CACHE, and this login is the one
+        # moment a live access token is already in hand.
+        #
+        # WITHOUT THIS, A BURST RIGHT AFTER LOGIN REVOKES THE SESSION. `store`
+        # deliberately drops any cached access token, so the cache is empty
+        # exactly here — and several `elan` processes starting at once then all
+        # miss it, all call `refresh` with the SAME refresh token, and an issuer
+        # that rotates treats the second use as a breach and revokes the whole
+        # grant. Measured: a login followed by a parallel load test, and every
+        # command afterwards failed with "your session is no longer valid".
+        #
+        # Caching the token we were just given means the burst reads it instead
+        # of racing for a new one.
+        auth.cache_access(config.issuer, tokens)
+
+    identity = auth.claims(tokens.access_token)
+    print(f"\nsigned in as {identity.get('sub')}")
+    print(f"  tenant  {identity.get('tenant_id') or '(none in this token)'}")
+    if not identity.get("tenant_id"):
+        # THE ONE CLAIM EVERY ROUTE IS SCOPED BY. Without it the services
+        # refuse every request, and the cause is an issuer-side action rather
+        # than anything the developer did.
+        print("\nwarning: this token carries no `tenant_id`, so every request "
+              "will be refused.\n         That claim is added by an action on "
+              "the issuer, not by the CLI.", file=sys.stderr)
+    return 0
+
+
+def _whoami(config: Config) -> int:
+    if not config.signed_in_possible:
+        print("not signed in. Run `elan login`.")
+        return 1
+    if not auth.stored(config.issuer):
+        print("not signed in. Run `elan login`.")
+        return 1
+
+    # THROUGH `Api.token()` RATHER THAN `auth.refresh()` DIRECTLY. This called
+    # refresh unconditionally, so `elan whoami` — the command somebody runs to
+    # CHECK a session — rotated the refresh token every time it ran, and cached
+    # nothing. On an issuer that rotates, a diagnostic that mutates the thing it
+    # reports on is the worst shape available: it also left the next command to
+    # race for a token this one had already invalidated.
+    #
+    # `Api.token()` consults the cache first and writes it back, so this is now
+    # free when a session is warm and one refresh when it is not.
+    try:
+        access = Api(config).token()
+    except ApiError as exc:
+        print(str(exc))
+        return 1
+    identity = auth.claims(access)
+    print(f"{identity.get('sub')}")
+    print(f"  tenant  {identity.get('tenant_id') or '(none)'}")
+    print(f"  issuer  {config.issuer}")
+    print(f"  api     {config.api}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())