profile.py 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164
  1. """``hermes profile`` subcommand parser."""
  2. from __future__ import annotations
  3. from typing import Callable
  4. def build_profile_parser(subparsers, *, cmd_profile: Callable) -> None:
  5. """Attach the ``profile`` subcommand to ``subparsers``."""
  6. profile_parser = subparsers.add_parser(
  7. "profile", help="Manage profiles — multiple isolated Hermes instances")
  8. profile_subparsers = profile_parser.add_subparsers(dest="profile_action")
  9. profile_subparsers.add_parser("list", help="List all profiles")
  10. profile_use = profile_subparsers.add_parser("use", help="Set sticky default profile")
  11. profile_use.add_argument("profile_name", help="Profile name (or 'default')")
  12. profile_create = profile_subparsers.add_parser("create", help="Create a new profile")
  13. profile_create.add_argument("profile_name", help="Profile name (lowercase, alphanumeric)")
  14. profile_create.add_argument(
  15. "--clone", action="store_true",
  16. help="Copy config.yaml, .env, SOUL.md, and skills from active profile "
  17. "(messaging bot tokens/allowlists are left behind; see --clone-channels)")
  18. profile_create.add_argument(
  19. "--clone-all", action="store_true",
  20. help="Full copy of active profile (all state, excluding per-profile history and messaging channels)")
  21. profile_create.add_argument(
  22. "--clone-from", metavar="SOURCE",
  23. help="Source profile to clone from; implies --clone unless --clone-all is set")
  24. profile_create.add_argument(
  25. "--clone-channels", action="store_true",
  26. help="Also copy the source's messaging channels (bot tokens, allowlists, platform sections). "
  27. "Two profiles holding one bot token collide; refused when the source is served by a live "
  28. "multiplexed gateway.")
  29. profile_create.add_argument(
  30. "--sync-imports", action="store_true",
  31. help="With --clone/--clone-from: also carry over the `hermes import-agent` sync manifest so "
  32. "the new profile stays registered against the same Claude Code / Codex trees "
  33. "(`hermes -p <name> import-agent --sync`). Never syncs config from the source profile.")
  34. profile_create.add_argument(
  35. "--no-alias", action="store_true", help="Skip wrapper script creation")
  36. profile_create.add_argument(
  37. "--no-skills", action="store_true",
  38. help="Create an empty profile with no bundled skills (opts out of `hermes update` skill sync)",
  39. )
  40. profile_create.add_argument(
  41. "--description", default=None,
  42. help="One- or two-sentence description of what this profile is good at. "
  43. "Used by the kanban decomposer to route tasks based on role instead "
  44. "of profile name alone. Skip and add later via `hermes profile describe`.")
  45. profile_delete = profile_subparsers.add_parser("delete", help="Delete a profile")
  46. profile_delete.add_argument("profile_name", help="Profile to delete")
  47. profile_delete.add_argument("-y", "--yes", action="store_true", help="Skip confirmation prompt")
  48. profile_describe = profile_subparsers.add_parser(
  49. "describe", help="Read or set a profile's description (used by the kanban orchestrator)")
  50. profile_describe.add_argument(
  51. "profile_name", nargs="?", default=None,
  52. help="Profile to describe (omit + use --all --auto to sweep)")
  53. profile_describe.add_argument(
  54. "--text", default=None,
  55. help="Set description to this exact text (overwrites any existing description)")
  56. profile_describe.add_argument(
  57. "--auto", action="store_true",
  58. help="Auto-generate description via the auxiliary LLM "
  59. "(uses auxiliary.profile_describer)")
  60. profile_describe.add_argument(
  61. "--overwrite", action="store_true",
  62. help="With --auto, replace user-authored descriptions too (default: only "
  63. "fill in missing or previously-auto descriptions)")
  64. profile_describe.add_argument(
  65. "--all", dest="all_missing", action="store_true",
  66. help="With --auto, run on every profile missing a description")
  67. profile_show = profile_subparsers.add_parser("show", help="Show profile details")
  68. profile_show.add_argument("profile_name", help="Profile to show")
  69. profile_alias = profile_subparsers.add_parser("alias", help="Manage wrapper scripts")
  70. profile_alias.add_argument("profile_name", help="Profile name")
  71. profile_alias.add_argument("--remove", action="store_true", help="Remove the wrapper script")
  72. profile_alias.add_argument(
  73. "--name", dest="alias_name", metavar="NAME",
  74. help="Custom alias name (default: profile name)")
  75. profile_rename = profile_subparsers.add_parser(
  76. "rename", help="Rename a profile ('default': sets a display name; id unchanged)")
  77. profile_rename.add_argument("old_name", help="Current profile name")
  78. profile_rename.add_argument(
  79. "new_name",
  80. help="New profile name (for 'default': a display name — the canonical id stays 'default')")
  81. profile_purge = profile_subparsers.add_parser(
  82. "purge-identity",
  83. help="Retry a deleted profile's session/routing identity purge",
  84. description="Re-run the session/routing identity purge that `hermes profile delete` performs "
  85. "automatically. The profile directory is already gone when this is needed: state still "
  86. "keyed by the deleted profile name (routing keys, heartbeats, routing/delivery rows) is "
  87. "deleted. Run it after restarting the gateway (which reloads the routing index from the "
  88. "DB) or after stopping it. Idempotent.")
  89. profile_purge.add_argument("profile_name", help="Deleted profile name")
  90. profile_migrate = profile_subparsers.add_parser(
  91. "migrate-identity",
  92. help="Retry a renamed profile's session/routing identity migration",
  93. description="Re-run the session/routing identity migration that `hermes profile rename` "
  94. "performs automatically. The rename has already happened when this is needed, so pass "
  95. "the OLD and NEW names: state still keyed by the old profile name (session keys, "
  96. "profile_name, heartbeats, routing/delivery rows) is rekeyed to the new one. Run it "
  97. "after restarting the gateway (which reloads the routing index from the DB) or after "
  98. "stopping it. Idempotent.")
  99. profile_migrate.add_argument("old_name", help="Profile name before the rename")
  100. profile_migrate.add_argument("new_name", help="Profile name after the rename")
  101. profile_export = profile_subparsers.add_parser("export", help="Export a profile to archive")
  102. profile_export.add_argument("profile_name", help="Profile to export")
  103. profile_export.add_argument(
  104. "-o", "--output", default=None,
  105. help="Output file (default: a managed profile-exports/<name>-<timestamp>.tar.gz "
  106. "under the default Hermes home)")
  107. profile_import = profile_subparsers.add_parser("import", help="Import a profile from archive")
  108. profile_import.add_argument("archive", help="Path to .tar.gz archive")
  109. profile_import.add_argument(
  110. "--name", dest="import_name", metavar="NAME",
  111. help="Profile name (default: inferred from archive)")
  112. # ---------- Distribution subcommands (issue #20456) ----------
  113. profile_install = profile_subparsers.add_parser(
  114. "install", help="Install a profile distribution from a git URL or local directory",
  115. description="Install a Hermes profile distribution. SOURCE can be a git URL "
  116. "(github.com/user/repo, https://..., git@...) or a local "
  117. "directory containing distribution.yaml at its root.")
  118. profile_install.add_argument("source", help="Distribution source (git URL or local directory)")
  119. profile_install.add_argument(
  120. "--name", dest="install_name", metavar="NAME",
  121. help="Override profile name (default: read from manifest)")
  122. profile_install.add_argument(
  123. "--alias", action="store_true",
  124. help="Create a shell wrapper alias for the installed profile")
  125. profile_install.add_argument(
  126. "--force", action="store_true",
  127. help="Overwrite an existing profile of the same name (user data preserved)")
  128. profile_install.add_argument(
  129. "-y", "--yes", action="store_true", help="Skip manifest preview confirmation")
  130. profile_update = profile_subparsers.add_parser(
  131. "update", help="Re-pull a distribution and apply updates (user data preserved)",
  132. description="Fetch the distribution from its recorded source and overwrite "
  133. "distribution-owned files (SOUL.md, mcp.json) and the skills and cron jobs "
  134. "the distribution ships; skills or cron jobs you added yourself stay in place. "
  135. "User data (memories, sessions, auth, .env) is never touched. "
  136. "config.yaml is preserved unless --force-config is passed.")
  137. profile_update.add_argument("profile_name", help="Profile to update")
  138. profile_update.add_argument(
  139. "--force-config", action="store_true",
  140. help="Also overwrite config.yaml (normally preserved to keep user overrides)")
  141. profile_update.add_argument("-y", "--yes", action="store_true", help="Skip confirmation")
  142. profile_info = profile_subparsers.add_parser(
  143. "info", help="Show a profile's distribution manifest (version, requirements, source)")
  144. profile_info.add_argument("profile_name", help="Profile to inspect")
  145. profile_parser.set_defaults(func=cmd_profile)