Skip to content

app

Class info

Classes

Name Children Inherits
ModelSelection
pyt3client.models.tools
    PendingRequestInput
    pyt3client.models.tools
      ProjectListInput
      pyt3client.models.tools
        ProviderOptionSelection
        pyt3client.models.tools
          Runtime
          pyt3client.cli.app
          Per-invocation state; tests pass one as `obj\=` to inject an httpx transport.
            T3AuthError
            pyt3client.errors
            Signing in failed, or the server no longer accepts the credential.
              T3Client
              pyt3client.client
              Typed client for one T3 Code environment, over its `/mcp` endpoint.
                T3Error
                pyt3client.errors
                Base class for every error pyt3client raises.
                T3HttpError
                pyt3client.errors
                The server answered with an unexpected HTTP status.
                  T3McpError
                  pyt3client.errors
                  The server answered a request with a JSON-RPC error.
                    T3ProtocolError
                    pyt3client.errors
                    The server answered in a shape this client does not understand.
                      T3ToolError
                      pyt3client.errors
                      A tool call was refused.
                        ThreadInterruptInput
                        pyt3client.models.tools
                          ThreadLaunchInput
                          pyt3client.models.tools
                            ThreadListInput
                            pyt3client.models.tools
                              ThreadReadInput
                              pyt3client.models.tools
                                ThreadSearchInput
                                pyt3client.models.tools
                                  ThreadSendInput
                                  pyt3client.models.tools
                                    WorkspaceStrategy
                                    pyt3client.models.tools
                                    'worktree': new checkout from `baseRef`. Honor a requested base. Otherwise, independent work uses the default branch as `remote/branch` (e.g. `origin/main`) with `startFromOrigin: true`; with no remote, use the local default branch. Required unpublished commits and dependent or stacked work use their local base with `startFromOrigin: false`. 'existing_worktree': bind `worktreePath`, a project worktree. 'root': project checkout, the default, not your worktree. Uncommitted edits are not copied.

                                      🛈 DocStrings

                                      The pyt3 command: drive a (possibly remote) T3 Code environment from a shell.

                                      T3 Code's own t3 CLI only works on the machine that runs the server (it reads the local data directory). pyt3 signs in to any environment's /mcp once (pyt3 login) and then works from anywhere that can reach it.

                                      Exit codes follow upstream t3 thread ... --wait: 0 when the run completed, 1 when it failed, was cancelled or interrupted (or on any error), 2 when the agent waits for an answer or approval, and 3 when --timeout ran out first.

                                      Runtime dataclass

                                      Per-invocation state; tests pass one as obj= to inject an httpx transport.

                                      Source code in src/pyt3client/cli/app.py
                                       99
                                      100
                                      101
                                      102
                                      103
                                      104
                                      105
                                      106
                                      107
                                      @dataclass
                                      class Runtime:
                                          """Per-invocation state; tests pass one as `obj=` to inject an httpx transport."""
                                      
                                          transport: httpx.AsyncBaseTransport | None = None
                                          env: str | None = None
                                      
                                          def http_client(self) -> httpx.AsyncClient:
                                              return httpx.AsyncClient(transport=self.transport, timeout=60)
                                      

                                      answer

                                      answer(
                                          ctx: Context,
                                          thread: Annotated[str, Argument(help="Thread id.")],
                                          request_id: Annotated[str, Argument(help="Request id from `pyt3 pending`.")],
                                          answers: Annotated[
                                              list[str],
                                              Argument(
                                                  help="question-id=answer, where the answer is an option value or label, or free text. Repeat a question id to select several options."
                                              ),
                                          ],
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Answer an agent's pending question. Cannot approve permission requests.

                                      Source code in src/pyt3client/cli/app.py
                                      894
                                      895
                                      896
                                      897
                                      898
                                      899
                                      900
                                      901
                                      902
                                      903
                                      904
                                      905
                                      906
                                      907
                                      908
                                      909
                                      910
                                      911
                                      912
                                      913
                                      914
                                      915
                                      916
                                      917
                                      918
                                      919
                                      920
                                      921
                                      922
                                      923
                                      924
                                      925
                                      926
                                      927
                                      928
                                      929
                                      930
                                      931
                                      932
                                      933
                                      934
                                      935
                                      936
                                      @app.command()
                                      def answer(
                                          ctx: typer.Context,
                                          thread: Annotated[str, typer.Argument(help="Thread id.")],
                                          request_id: Annotated[str, typer.Argument(help="Request id from `pyt3 pending`.")],
                                          answers: Annotated[
                                              list[str],
                                              typer.Argument(
                                                  help="question-id=answer, where the answer is an option value or label, or free"
                                                  " text. Repeat a question id to select several options."
                                              ),
                                          ],
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Answer an agent's pending question. Cannot approve permission requests."""
                                          parsed: dict[str, JsonValue] = {}
                                          for raw in answers:
                                              question_id, sep, value = raw.partition("=")
                                              if not sep or not question_id.strip():
                                                  _fail(f"answers take question-id=answer, got {raw!r}")
                                              key = question_id.strip()
                                              match parsed.get(key):
                                                  case None:
                                                      parsed[key] = value
                                                  case list() as values:
                                                      values.append(value)
                                                  case previous:
                                                      parsed[key] = [previous, value]
                                      
                                          async def go(t3: T3Client) -> int:
                                              result = await t3.call(
                                                  PENDING_REQUEST,
                                                  PendingRequestInput(
                                                      action="respond", thread_id=thread, request_id=request_id, answers=parsed
                                                  ),
                                              )
                                              if as_json:
                                                  _echo_json(result)
                                              else:
                                                  typer.echo("Answered.")
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      envs

                                      envs(as_json: JsonFlag = False) -> None
                                      

                                      List saved environments (never prints tokens).

                                      Source code in src/pyt3client/cli/app.py
                                      521
                                      522
                                      523
                                      524
                                      525
                                      526
                                      527
                                      528
                                      529
                                      530
                                      531
                                      532
                                      533
                                      534
                                      535
                                      536
                                      537
                                      538
                                      539
                                      540
                                      541
                                      542
                                      543
                                      544
                                      545
                                      546
                                      547
                                      548
                                      549
                                      550
                                      551
                                      552
                                      553
                                      554
                                      @app.command()
                                      def envs(as_json: JsonFlag = False) -> None:
                                          """List saved environments (never prints tokens)."""
                                          try:
                                              environments = store.load()
                                              native = store.load_native()
                                          except store.StoreError as error:
                                              _fail(str(error))
                                          if as_json:
                                              listed: dict[str, JsonValue] = {}
                                              for alias, creds in environments.items():
                                                  summary = _env_summary(creds)
                                                  if (signed_in := native.get(alias)) is not None:
                                                      summary["native"] = {
                                                          "expiresAt": signed_in.expires_at.isoformat(),
                                                          "expired": store.is_expired(signed_in),
                                                      }
                                                  listed[alias] = summary
                                              _echo_json(listed)
                                              return
                                          if not environments:
                                              typer.echo("No environment saved. Run `pyt3 login <url> <pairing-code>`.")
                                              return
                                          for alias, credentials in sorted(environments.items()):
                                              state = (
                                                  "EXPIRED"
                                                  if store.is_expired(credentials)
                                                  else f"until {credentials.expires_at:%Y-%m-%d}"
                                              )
                                              native_state = "native" if alias in native else "-"
                                              typer.echo(
                                                  f"{alias}\t{credentials.base_url}\t{credentials.access}\t{state}"
                                                  f"\t{credentials.environment_id}\t{native_state}"
                                              )
                                      

                                      interrupt

                                      interrupt(
                                          ctx: Context,
                                          thread: Annotated[str, Argument(help="Thread id.")],
                                          run: Annotated[
                                              str | None, Option(help="Run to interrupt (default: the newest running).")
                                          ] = None,
                                          reason: Annotated[str | None, Option(help="Why; shown in the thread.")] = None,
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Interrupt a thread's running turn.

                                      Source code in src/pyt3client/cli/app.py
                                      834
                                      835
                                      836
                                      837
                                      838
                                      839
                                      840
                                      841
                                      842
                                      843
                                      844
                                      845
                                      846
                                      847
                                      848
                                      849
                                      850
                                      851
                                      852
                                      853
                                      854
                                      855
                                      856
                                      857
                                      858
                                      859
                                      @app.command()
                                      def interrupt(
                                          ctx: typer.Context,
                                          thread: Annotated[str, typer.Argument(help="Thread id.")],
                                          run: Annotated[
                                              str | None, typer.Option(help="Run to interrupt (default: the newest running).")
                                          ] = None,
                                          reason: Annotated[str | None, typer.Option(help="Why; shown in the thread.")] = None,
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Interrupt a thread's running turn."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              params = ThreadInterruptInput(thread_id=thread)
                                              if run is not None:
                                                  params.run_id = run
                                              if reason is not None:
                                                  params.reason = reason
                                              result = await t3.call(THREAD_INTERRUPT, params)
                                              if as_json:
                                                  _echo_json(result)
                                              else:
                                                  typer.echo(f"{result.run_id or '-'}\t{result.status}")
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      login

                                      login(
                                          ctx: Context,
                                          url: Annotated[str, Argument(help="Environment address, e.g. https://host:3773.")],
                                          pairing_code: Annotated[str, Argument(help="Code from `t3 auth pairing create`.")],
                                          access: Annotated[
                                              Literal["read-only", "approval-required", "auto-accept-edits", "auto", "full-access"],
                                              Option(help="What this CLI may do. App approval codes (AUTO-…) set their own."),
                                          ] = "auto",
                                          name: Annotated[
                                              str | None, Option("--name", help="Alias to save it as (default: its label).")
                                          ] = None,
                                          client_name: Annotated[
                                              str, Option(help="Label the environment shows for this sign-in.")
                                          ] = "pyt3",
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Sign in with a one-time pairing code and save the token.

                                      Source code in src/pyt3client/cli/app.py
                                      372
                                      373
                                      374
                                      375
                                      376
                                      377
                                      378
                                      379
                                      380
                                      381
                                      382
                                      383
                                      384
                                      385
                                      386
                                      387
                                      388
                                      389
                                      390
                                      391
                                      392
                                      393
                                      394
                                      395
                                      396
                                      397
                                      398
                                      399
                                      400
                                      401
                                      402
                                      403
                                      404
                                      405
                                      406
                                      407
                                      408
                                      409
                                      410
                                      411
                                      412
                                      413
                                      414
                                      415
                                      416
                                      417
                                      418
                                      @app.command()
                                      def login(
                                          ctx: typer.Context,
                                          url: Annotated[str, typer.Argument(help="Environment address, e.g. https://host:3773.")],
                                          pairing_code: Annotated[str, typer.Argument(help="Code from `t3 auth pairing create`.")],
                                          access: Annotated[
                                              Literal["read-only", "approval-required", "auto-accept-edits", "auto", "full-access"],
                                              typer.Option(help="What this CLI may do. App approval codes (AUTO-…) set their own."),
                                          ] = "auto",
                                          name: Annotated[
                                              str | None, typer.Option("--name", help="Alias to save it as (default: its label).")
                                          ] = None,
                                          client_name: Annotated[
                                              str, typer.Option(help="Label the environment shows for this sign-in.")
                                          ] = "pyt3",
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Sign in with a one-time pairing code and save the token."""
                                          runtime = _runtime(ctx)
                                          level: McpAccess = access
                                      
                                          async def go() -> tuple[str, T3Credentials]:
                                              async with runtime.http_client() as http:
                                                  credentials = await pair(
                                                      url, pairing_code, access=level, client_name=client_name, http_client=http
                                                  )
                                                  descriptor = await fetch_descriptor(credentials.base_url, http_client=http)
                                              return name or store.default_alias(descriptor.label, credentials.base_url), credentials
                                      
                                          try:
                                              alias, credentials = asyncio.run(go())
                                              environments = store.load()
                                          except T3AuthError as error:
                                              _fail(f"auth: {error}")
                                          except (T3Error, httpx.HTTPError) as error:
                                              _fail(f"cannot sign in at {url}: {error}")
                                          except store.StoreError as error:
                                              _fail(str(error))
                                          environments[alias] = credentials
                                          path = store.save(environments)
                                          if as_json:
                                              _echo_json({"alias": alias, "path": str(path)} | _env_summary(credentials))
                                              return
                                          typer.echo(
                                              f"Signed in to {alias} ({credentials.base_url}) as {credentials.access},"
                                              f" valid until {credentials.expires_at:%Y-%m-%d}."
                                          )
                                      

                                      login_native

                                      login_native(
                                          ctx: Context,
                                          url: Annotated[str, Argument(help="Environment address, e.g. https://host:3773.")],
                                          pairing_token: Annotated[
                                              str, Argument(help="Token from `t3 auth pairing create` (not an MCP code).")
                                          ],
                                          name: Annotated[
                                              str | None,
                                              Option(
                                                  "--name",
                                                  help="Alias to save it as (default: the MCP sign-in of this URL, or its label).",
                                              ),
                                          ] = None,
                                          client_name: Annotated[
                                              str, Option(help="Label the environment shows for this sign-in.")
                                          ] = "pyt3",
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Sign in to the native WebSocket RPC (live streaming, approvals) and save the token.

                                      The native surface rejects MCP tokens, so this is a second sign-in, kept under the same alias as the environment's MCP one.

                                      Source code in src/pyt3client/cli/app.py
                                      421
                                      422
                                      423
                                      424
                                      425
                                      426
                                      427
                                      428
                                      429
                                      430
                                      431
                                      432
                                      433
                                      434
                                      435
                                      436
                                      437
                                      438
                                      439
                                      440
                                      441
                                      442
                                      443
                                      444
                                      445
                                      446
                                      447
                                      448
                                      449
                                      450
                                      451
                                      452
                                      453
                                      454
                                      455
                                      456
                                      457
                                      458
                                      459
                                      460
                                      461
                                      462
                                      463
                                      464
                                      465
                                      466
                                      467
                                      468
                                      469
                                      470
                                      471
                                      472
                                      473
                                      474
                                      475
                                      476
                                      477
                                      478
                                      479
                                      480
                                      481
                                      482
                                      483
                                      484
                                      485
                                      486
                                      @app.command("login-native")
                                      def login_native(
                                          ctx: typer.Context,
                                          url: Annotated[str, typer.Argument(help="Environment address, e.g. https://host:3773.")],
                                          pairing_token: Annotated[
                                              str, typer.Argument(help="Token from `t3 auth pairing create` (not an MCP code).")
                                          ],
                                          name: Annotated[
                                              str | None,
                                              typer.Option(
                                                  "--name",
                                                  help="Alias to save it as (default: the MCP sign-in of this URL, or its label).",
                                              ),
                                          ] = None,
                                          client_name: Annotated[
                                              str, typer.Option(help="Label the environment shows for this sign-in.")
                                          ] = "pyt3",
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Sign in to the native WebSocket RPC (live streaming, approvals) and save the token.
                                      
                                          The native surface rejects MCP tokens, so this is a second sign-in, kept under the
                                          same alias as the environment's MCP one.
                                          """
                                          from pyt3client.native import sign_in_native
                                      
                                          runtime = _runtime(ctx)
                                      
                                          async def go() -> tuple[str, T3NativeCredentials]:
                                              async with runtime.http_client() as http:
                                                  credentials = await sign_in_native(
                                                      url, pairing_token, label=client_name, http_client=http
                                                  )
                                                  if name is not None:
                                                      return name, credentials
                                                  for alias, saved in store.load().items():
                                                      if saved.base_url == credentials.base_url:
                                                          return alias, credentials
                                                  descriptor = await fetch_descriptor(credentials.base_url, http_client=http)
                                              return store.default_alias(descriptor.label, credentials.base_url), credentials
                                      
                                          try:
                                              alias, credentials = asyncio.run(go())
                                              native = store.load_native()
                                          except T3AuthError as error:
                                              _fail(f"auth: {error}")
                                          except (T3Error, httpx.HTTPError) as error:
                                              _fail(f"cannot sign in at {url}: {error}")
                                          except store.StoreError as error:
                                              _fail(str(error))
                                          native[alias] = credentials
                                          path = store.save_native(native)
                                          if as_json:
                                              summary: dict[str, JsonValue] = {
                                                  "alias": alias,
                                                  "path": str(path),
                                                  "url": credentials.base_url,
                                                  "scopes": list(credentials.scopes),
                                                  "expiresAt": credentials.expires_at.isoformat(),
                                              }
                                              _echo_json(summary)
                                              return
                                          typer.echo(
                                              f"Signed in natively to {alias} ({credentials.base_url}),"
                                              f" valid until {credentials.expires_at:%Y-%m-%d}."
                                          )
                                      

                                      logout

                                      logout(
                                          ctx: Context,
                                          alias: Annotated[
                                              str | None, Argument(help="Environment to forget (default: --env or the only one).")
                                          ] = None,
                                      ) -> None
                                      

                                      Forget a saved sign-in. Revoke it in T3 Code under Settings -> Sharing & access.

                                      Source code in src/pyt3client/cli/app.py
                                      489
                                      490
                                      491
                                      492
                                      493
                                      494
                                      495
                                      496
                                      497
                                      498
                                      499
                                      500
                                      501
                                      502
                                      503
                                      504
                                      505
                                      506
                                      507
                                      508
                                      @app.command()
                                      def logout(
                                          ctx: typer.Context,
                                          alias: Annotated[
                                              str | None, typer.Argument(help="Environment to forget (default: --env or the only one).")
                                          ] = None,
                                      ) -> None:
                                          """Forget a saved sign-in. Revoke it in T3 Code under Settings -> Sharing & access."""
                                          runtime = _runtime(ctx)
                                          try:
                                              environments = store.load()
                                              chosen, _ = store.select(environments, alias or runtime.env)
                                          except store.StoreError as error:
                                              _fail(str(error))
                                          del environments[chosen]
                                          store.save(environments)
                                          native = store.load_native()
                                          if native.pop(chosen, None) is not None:
                                              store.save_native(native)
                                          typer.echo(f"Forgot {chosen}. The token stays valid until revoked in T3 Code.")
                                      

                                      main

                                      main(
                                          ctx: Context,
                                          env: Annotated[
                                              str | None,
                                              Option("--env", envvar="PYT3_ENV", help="Saved environment alias (see `pyt3 envs`)."),
                                          ] = None,
                                      ) -> None
                                      

                                      Drive T3 Code environments (local or remote) over their MCP endpoint.

                                      Source code in src/pyt3client/cli/app.py
                                      123
                                      124
                                      125
                                      126
                                      127
                                      128
                                      129
                                      130
                                      131
                                      132
                                      133
                                      134
                                      @app.callback()
                                      def main(
                                          ctx: typer.Context,
                                          env: Annotated[
                                              str | None,
                                              typer.Option("--env", envvar="PYT3_ENV", help="Saved environment alias (see `pyt3 envs`)."),
                                          ] = None,
                                      ) -> None:
                                          """Drive T3 Code environments (local or remote) over their MCP endpoint."""
                                          runtime = ctx.obj if isinstance(ctx.obj, Runtime) else Runtime()
                                          runtime.env = env
                                          ctx.obj = runtime
                                      

                                      models

                                      models(ctx: Context, as_json: JsonFlag = False) -> None
                                      

                                      List providers and their models.

                                      Source code in src/pyt3client/cli/app.py
                                      560
                                      561
                                      562
                                      563
                                      564
                                      565
                                      566
                                      567
                                      568
                                      569
                                      570
                                      571
                                      572
                                      573
                                      574
                                      575
                                      576
                                      577
                                      578
                                      579
                                      580
                                      581
                                      582
                                      583
                                      584
                                      585
                                      @app.command()
                                      def models(ctx: typer.Context, as_json: JsonFlag = False) -> None:
                                          """List providers and their models."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              capabilities = await t3.call(ORCHESTRATOR_CAPABILITIES)
                                              if as_json:
                                                  _echo_json(capabilities)
                                                  return EXIT_OK
                                              for provider in capabilities.providers:
                                                  state = "can run" if provider.can_run_child_task else "unavailable"
                                                  label = f" ({provider.display_name})" if provider.display_name else ""
                                                  typer.echo(f"{provider.provider_instance_id}{label}  [{state}]")
                                                  for constraint in provider.constraints:
                                                      typer.echo(f"    ! {constraint}")
                                                  for model in provider.models:
                                                      options = ", ".join(
                                                          f"{option.id}={'|'.join(_option_value(value) for value in option.values)}"
                                                          for option in model.options or []
                                                      )
                                                      typer.echo(f"  {model.id}" + (f"  ({options})" if options else ""))
                                                  if provider.omitted_models:
                                                      typer.echo(f"  … {provider.omitted_models.root} more")
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      pending

                                      pending(
                                          ctx: Context, thread: Annotated[str, Argument(help="Thread id.")], as_json: JsonFlag = False
                                      ) -> None
                                      

                                      List the questions a thread's agent waits on (approvals are not listed).

                                      Source code in src/pyt3client/cli/app.py
                                      862
                                      863
                                      864
                                      865
                                      866
                                      867
                                      868
                                      869
                                      870
                                      871
                                      872
                                      873
                                      874
                                      875
                                      876
                                      877
                                      878
                                      879
                                      880
                                      881
                                      882
                                      883
                                      884
                                      885
                                      886
                                      887
                                      888
                                      889
                                      890
                                      891
                                      @app.command()
                                      def pending(
                                          ctx: typer.Context,
                                          thread: Annotated[str, typer.Argument(help="Thread id.")],
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """List the questions a thread's agent waits on (approvals are not listed)."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              listed = await t3.call(
                                                  PENDING_REQUEST, PendingRequestInput(action="list", thread_id=thread)
                                              )
                                              request_ids = _string_list(listed.root, "requestIds")
                                              requests: list[JsonValue] = []
                                              for request_id in request_ids:
                                                  read = await t3.call(
                                                      PENDING_REQUEST,
                                                      PendingRequestInput(action="read", thread_id=thread, request_id=request_id),
                                                  )
                                                  requests.append(read.root)
                                              if as_json:
                                                  _echo_json(requests)
                                                  return EXIT_OK
                                              if not requests:
                                                  typer.echo("No pending questions.")
                                              for request in requests:
                                                  _print_request(request)
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      projects

                                      projects(ctx: Context, as_json: JsonFlag = False) -> None
                                      

                                      List projects.

                                      Source code in src/pyt3client/cli/app.py
                                      588
                                      589
                                      590
                                      591
                                      592
                                      593
                                      594
                                      595
                                      596
                                      597
                                      598
                                      599
                                      600
                                      601
                                      @app.command()
                                      def projects(ctx: typer.Context, as_json: JsonFlag = False) -> None:
                                          """List projects."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              found = await _all_projects(t3)
                                              if as_json:
                                                  _echo_json([_dump(project) for project in found])
                                                  return EXIT_OK
                                              for project in found:
                                                  typer.echo(f"{project.id}\t{project.title}\t{project.workspace_root}")
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      send

                                      send(
                                          ctx: Context,
                                          thread: Annotated[str, Argument(help="Thread id.")],
                                          message: Annotated[str, Argument(help="Message; `-` reads stdin.")],
                                          mode: Annotated[
                                              Literal["auto", "queue", "steer", "restart"] | None,
                                              Option(
                                                  help="auto (default): start an idle thread, steer or queue a busy one; queue: run after active work; steer: into the running turn; restart: interrupt and restart with this message."
                                              ),
                                          ] = None,
                                          wait: Annotated[bool, Option(help="Wait for the run and print the reply.")] = False,
                                          timeout: TimeoutOption = None,
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Send a message to a thread.

                                      Source code in src/pyt3client/cli/app.py
                                      774
                                      775
                                      776
                                      777
                                      778
                                      779
                                      780
                                      781
                                      782
                                      783
                                      784
                                      785
                                      786
                                      787
                                      788
                                      789
                                      790
                                      791
                                      792
                                      793
                                      794
                                      795
                                      796
                                      797
                                      798
                                      799
                                      800
                                      801
                                      802
                                      803
                                      804
                                      805
                                      806
                                      807
                                      808
                                      809
                                      @app.command()
                                      def send(
                                          ctx: typer.Context,
                                          thread: Annotated[str, typer.Argument(help="Thread id.")],
                                          message: Annotated[str, typer.Argument(help="Message; `-` reads stdin.")],
                                          mode: Annotated[
                                              Literal["auto", "queue", "steer", "restart"] | None,
                                              typer.Option(
                                                  help="auto (default): start an idle thread, steer or queue a busy one;"
                                                  " queue: run after active work; steer: into the running turn;"
                                                  " restart: interrupt and restart with this message."
                                              ),
                                          ] = None,
                                          wait: Annotated[bool, typer.Option(help="Wait for the run and print the reply.")] = False,
                                          timeout: TimeoutOption = None,
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Send a message to a thread."""
                                          text = _read_message(message)
                                      
                                          async def go(t3: T3Client) -> int:
                                              params = ThreadSendInput(thread_id=thread, message=text)
                                              if mode is not None:
                                                  params.mode = mode
                                              sent = await t3.call(THREAD_SEND, params)
                                              if wait:
                                                  return await _wait_and_report(
                                                      t3, thread, sent.run_id, timeout=timeout, as_json=as_json, launched=sent
                                                  )
                                              if as_json:
                                                  _echo_json(sent)
                                              else:
                                                  typer.echo(f"{sent.run_id}\t{sent.status}")
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      show

                                      show(
                                          ctx: Context,
                                          thread: Annotated[str, Argument(help="Thread id.")],
                                          activity: Annotated[
                                              bool, Option(help="Include tool calls, reasoning and runtime requests.")
                                          ] = False,
                                          limit: Annotated[int, Option(min=1, max=100, help="Latest items to show.")] = 10,
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Show a thread's state and its latest messages.

                                      Source code in src/pyt3client/cli/app.py
                                      663
                                      664
                                      665
                                      666
                                      667
                                      668
                                      669
                                      670
                                      671
                                      672
                                      673
                                      674
                                      675
                                      676
                                      677
                                      678
                                      679
                                      680
                                      681
                                      682
                                      683
                                      684
                                      685
                                      686
                                      687
                                      688
                                      689
                                      690
                                      @app.command()
                                      def show(
                                          ctx: typer.Context,
                                          thread: Annotated[str, typer.Argument(help="Thread id.")],
                                          activity: Annotated[
                                              bool, typer.Option(help="Include tool calls, reasoning and runtime requests.")
                                          ] = False,
                                          limit: Annotated[int, typer.Option(min=1, max=100, help="Latest items to show.")] = 10,
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Show a thread's state and its latest messages."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              read = await _read_newest(t3, thread, limit=limit, activity=activity)
                                              if as_json:
                                                  _echo_json(read)
                                                  return EXIT_OK
                                              state = read.thread
                                              typer.echo(f"{state.title}  [{state.status}]  {state.provider_instance_id}/{state.model}")
                                              typer.echo(f"{state.thread_id}  {state.runtime_mode}/{state.interaction_mode}")
                                              if state.link:
                                                  typer.echo(state.link)
                                              typer.echo("")
                                              for item in read.items:
                                                  typer.echo(_item_line(item))
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      start

                                      start(
                                          ctx: Context,
                                          project: Annotated[str, Argument(help="Project id, or a folder inside a project.")],
                                          message: Annotated[str, Argument(help="First prompt; `-` reads stdin.")],
                                          title: Annotated[
                                              str | None, Option(help="Thread title (default: the message's first line).")
                                          ] = None,
                                          provider: Annotated[
                                              str | None, Option(help="Provider instance id (see `pyt3 models`).")
                                          ] = None,
                                          model: Annotated[str | None, Option(help="Model slug of that provider.")] = None,
                                          option: Annotated[list[str] | None, Option(help="Model option id=value (repeatable).")] = None,
                                          mode: Annotated[
                                              Literal["approval-required", "auto-accept-edits", "auto", "full-access"] | None,
                                              Option(help="Runtime mode (default: the project's)."),
                                          ] = None,
                                          plan: Annotated[bool, Option(help="Start in plan mode.")] = False,
                                          worktree: Annotated[
                                              str | None, Option(help="Run in a new worktree from this branch, tag or commit.")
                                          ] = None,
                                          branch: Annotated[str | None, Option(help="Branch name for the new worktree.")] = None,
                                          wait: Annotated[bool, Option(help="Wait for the run and print the reply.")] = False,
                                          timeout: TimeoutOption = None,
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Start a thread and print its id (or, with --wait, the agent's reply).

                                      Source code in src/pyt3client/cli/app.py
                                      696
                                      697
                                      698
                                      699
                                      700
                                      701
                                      702
                                      703
                                      704
                                      705
                                      706
                                      707
                                      708
                                      709
                                      710
                                      711
                                      712
                                      713
                                      714
                                      715
                                      716
                                      717
                                      718
                                      719
                                      720
                                      721
                                      722
                                      723
                                      724
                                      725
                                      726
                                      727
                                      728
                                      729
                                      730
                                      731
                                      732
                                      733
                                      734
                                      735
                                      736
                                      737
                                      738
                                      739
                                      740
                                      741
                                      742
                                      743
                                      744
                                      745
                                      746
                                      747
                                      748
                                      749
                                      750
                                      751
                                      752
                                      753
                                      754
                                      755
                                      756
                                      757
                                      758
                                      759
                                      760
                                      761
                                      762
                                      763
                                      764
                                      765
                                      766
                                      767
                                      768
                                      769
                                      770
                                      771
                                      @app.command()
                                      def start(
                                          ctx: typer.Context,
                                          project: Annotated[str, typer.Argument(help="Project id, or a folder inside a project.")],
                                          message: Annotated[str, typer.Argument(help="First prompt; `-` reads stdin.")],
                                          title: Annotated[
                                              str | None, typer.Option(help="Thread title (default: the message's first line).")
                                          ] = None,
                                          provider: Annotated[
                                              str | None, typer.Option(help="Provider instance id (see `pyt3 models`).")
                                          ] = None,
                                          model: Annotated[str | None, typer.Option(help="Model slug of that provider.")] = None,
                                          option: Annotated[
                                              list[str] | None, typer.Option(help="Model option id=value (repeatable).")
                                          ] = None,
                                          mode: Annotated[
                                              Literal["approval-required", "auto-accept-edits", "auto", "full-access"] | None,
                                              typer.Option(help="Runtime mode (default: the project's)."),
                                          ] = None,
                                          plan: Annotated[bool, typer.Option(help="Start in plan mode.")] = False,
                                          worktree: Annotated[
                                              str | None, typer.Option(help="Run in a new worktree from this branch, tag or commit.")
                                          ] = None,
                                          branch: Annotated[str | None, typer.Option(help="Branch name for the new worktree.")] = None,
                                          wait: Annotated[bool, typer.Option(help="Wait for the run and print the reply.")] = False,
                                          timeout: TimeoutOption = None,
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Start a thread and print its id (or, with --wait, the agent's reply)."""
                                          if (provider is None) != (model is None):
                                              _fail("pass --provider and --model together")
                                          if option and provider is None:
                                              _fail("--option needs --provider and --model")
                                          if branch is not None and worktree is None:
                                              _fail("--branch needs --worktree")
                                          text = _read_message(message)
                                          runtime_mode: RuntimeMode | None = mode
                                          interaction: InteractionMode | None = "plan" if plan else None
                                      
                                          async def go(t3: T3Client) -> int:
                                              params = ThreadLaunchInput(
                                                  project_id=await _resolve_project(t3, project),
                                                  title=title or text.strip().splitlines()[0][:120],
                                                  message=text,
                                              )
                                              if provider is not None and model is not None:
                                                  selection = ModelSelection(instance_id=provider, model=model)
                                                  if option:
                                                      selection.options = [_parse_option(raw) for raw in option]
                                                  params.model_selection = selection
                                              if runtime_mode is not None:
                                                  params.runtime_mode = runtime_mode
                                              if interaction is not None:
                                                  params.interaction_mode = interaction
                                              if worktree is not None:
                                                  strategy = WorkspaceStrategy(type="worktree", base_ref=worktree)
                                                  if branch is not None:
                                                      strategy.branch = branch
                                                  params.workspace_strategy = strategy
                                              launched = await t3.call(THREAD_LAUNCH, params)
                                              if wait:
                                                  return await _wait_and_report(
                                                      t3,
                                                      launched.thread_id,
                                                      launched.run_id,
                                                      timeout=timeout,
                                                      as_json=as_json,
                                                      launched=launched,
                                                  )
                                              if as_json:
                                                  _echo_json(launched)
                                              else:
                                                  typer.echo(launched.thread_id)
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      threads

                                      threads(
                                          ctx: Context,
                                          project: Annotated[
                                              str | None, Option(help="Project id or folder (default: all projects).")
                                          ] = None,
                                          all_threads: Annotated[bool, Option("--all", help="Include subagent threads.")] = False,
                                          status: Annotated[
                                              list[ThreadStatus] | None, Option(help="Only threads in this status (repeatable).")
                                          ] = None,
                                          search: Annotated[
                                              str | None, Option(help="Search titles, branches, PRs and messages instead.")
                                          ] = None,
                                          limit: Annotated[int, Option(min=1, max=100)] = 50,
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      List threads, newest first, or search them.

                                      Source code in src/pyt3client/cli/app.py
                                      604
                                      605
                                      606
                                      607
                                      608
                                      609
                                      610
                                      611
                                      612
                                      613
                                      614
                                      615
                                      616
                                      617
                                      618
                                      619
                                      620
                                      621
                                      622
                                      623
                                      624
                                      625
                                      626
                                      627
                                      628
                                      629
                                      630
                                      631
                                      632
                                      633
                                      634
                                      635
                                      636
                                      637
                                      638
                                      639
                                      640
                                      641
                                      642
                                      643
                                      644
                                      645
                                      646
                                      647
                                      648
                                      649
                                      650
                                      651
                                      652
                                      653
                                      654
                                      655
                                      656
                                      657
                                      658
                                      659
                                      660
                                      @app.command()
                                      def threads(
                                          ctx: typer.Context,
                                          project: Annotated[
                                              str | None, typer.Option(help="Project id or folder (default: all projects).")
                                          ] = None,
                                          all_threads: Annotated[bool, typer.Option("--all", help="Include subagent threads.")] = False,
                                          status: Annotated[
                                              list[ThreadStatus] | None, typer.Option(help="Only threads in this status (repeatable).")
                                          ] = None,
                                          search: Annotated[
                                              str | None, typer.Option(help="Search titles, branches, PRs and messages instead.")
                                          ] = None,
                                          limit: Annotated[int, typer.Option(min=1, max=100)] = 50,
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """List threads, newest first, or search them."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              project_id = await _resolve_project(t3, project) if project else None
                                              if search is not None:
                                                  found = await t3.call(
                                                      THREAD_SEARCH,
                                                      ThreadSearchInput(query=search, limit=min(limit, 50))
                                                      if project_id is None
                                                      else ThreadSearchInput(query=search, limit=min(limit, 50), project_id=project_id),
                                                  )
                                                  if as_json:
                                                      _echo_json(found)
                                                      return EXIT_OK
                                                  for match in found.matches:
                                                      snippet = f"  {match.snippet.root}" if match.snippet else ""
                                                      typer.echo(f"{match.thread_id}\t{match.title}\t[{match.source}]{snippet}")
                                                  return EXIT_OK
                                              params = ThreadListInput(limit=limit)
                                              if project_id is None:
                                                  params.all_projects = True
                                              else:
                                                  params.project_id = project_id
                                              if all_threads:
                                                  params.include_subagents = True
                                              if status:
                                                  params.statuses = list(status)
                                              listed = await t3.call(THREAD_LIST, params)
                                              if as_json:
                                                  _echo_json(listed)
                                                  return EXIT_OK
                                              for thread in listed.threads:
                                                  typer.echo(
                                                      f"{thread.thread_id}\t{thread.status}\t{thread.title}"
                                                      f"\t{thread.provider_instance_id}/{thread.model}"
                                                  )
                                              if listed.total > len(listed.threads):
                                                  typer.echo(f"… {listed.total - len(listed.threads)} more (raise --limit)", err=True)
                                              return EXIT_OK
                                      
                                          _run(ctx, go)
                                      

                                      wait_command

                                      wait_command(
                                          ctx: Context,
                                          thread: Annotated[str, Argument(help="Thread id.")],
                                          run: Annotated[str | None, Option(help="Run to wait for (default: the latest).")] = None,
                                          timeout: TimeoutOption = None,
                                          as_json: JsonFlag = False,
                                      ) -> None
                                      

                                      Wait until a thread's run ends; the exit code tells how it ended.

                                      Source code in src/pyt3client/cli/app.py
                                      812
                                      813
                                      814
                                      815
                                      816
                                      817
                                      818
                                      819
                                      820
                                      821
                                      822
                                      823
                                      824
                                      825
                                      826
                                      827
                                      828
                                      829
                                      830
                                      831
                                      @app.command(name="wait")
                                      def wait_command(
                                          ctx: typer.Context,
                                          thread: Annotated[str, typer.Argument(help="Thread id.")],
                                          run: Annotated[str | None, typer.Option(help="Run to wait for (default: the latest).")] = None,
                                          timeout: TimeoutOption = None,
                                          as_json: JsonFlag = False,
                                      ) -> None:
                                          """Wait until a thread's run ends; the exit code tells how it ended."""
                                      
                                          async def go(t3: T3Client) -> int:
                                              result = await t3.wait_for_thread(thread, run_id=run, timeout=timeout)
                                              if as_json:
                                                  _echo_json(result)
                                              else:
                                                  state = "timed out" if result.timed_out else result.status
                                                  typer.echo(f"{result.run_id or '-'}\t{state}")
                                              return _wait_exit_code(result)
                                      
                                          _run(ctx, go)