JGC-473 - Add AI-agent help text to application commands

apptrust/commands/application/create_app_cmd.go

@@ -168,6 +168,30 @@ func GetCreateAppCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.AppCreate,
 		Description: "Create a new application.",
+		AIDescription: `Create a new application in AppTrust, identified by an application key and belonging to a project.
+
+When to use:
+- Register a new logical application that will own future versions and package bindings.
+- Bootstrap AppTrust governance for a new service or product.
+
+Prerequisites:
+- A configured server with AppTrust enabled.
+- Create permission on the target project.
+- Either --project (mandatory when no --spec is used) or a --spec file with project_key set.
+
+Common patterns:
+  $ jf apptrust app-create my-app --project=default
+  $ jf apptrust app-create my-app --project=default --application-name="My App" --desc="Service X"
+  $ jf apptrust app-create my-app --project=default --business-criticality=high --maturity-level=production
+  $ jf apptrust app-create my-app --project=default --labels="team=core;area=platform" --user-owners="alice;bob"
+  $ jf apptrust app-create my-app --spec=app-spec.json --spec-vars="ENV=prod"
+
+Gotchas:
+- --spec is mutually exclusive with --application-name, --project, --desc, --business-criticality, --maturity-level, --labels, --user-owners, --group-owners.
+- If --application-name is omitted, the application-key is used as the display name.
+- --labels uses semicolon separators (not commas) and key=value pairs.
+
+Related: jf apptrust app-update, jf apptrust app-delete, jf apptrust version-create`,
 		Category:    common.CategoryApplication,
 		Aliases:     []string{"ac"},
 		Arguments: []components.Argument{

apptrust/commands/application/delete_app_cmd.go

@@ -60,6 +60,26 @@ func GetDeleteAppCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.AppDelete,
 		Description: "Delete an application.",
+		AIDescription: `Permanently delete an application from AppTrust, identified by its application key.
+
+When to use:
+- Remove an application that is no longer maintained.
+- Clean up after creating an application with the wrong key.
+
+Prerequisites:
+- The application must exist.
+- Configured server and delete permission on the application's project.
+- Existing versions/bindings under the application may need to be removed first depending on platform policy.
+
+Common patterns:
+  $ jf apptrust app-delete my-app
+  $ jf at ad my-app --server-id=my-server
+
+Gotchas:
+- Deletion is irreversible and may fail if the application still has active versions or package bindings.
+- This does not delete artifacts in Artifactory; only the AppTrust application record is removed.
+
+Related: jf apptrust app-create, jf apptrust version-delete, jf apptrust package-unbind`,
 		Category:    common.CategoryApplication,
 		Aliases:     []string{"ad"},
 		Arguments: []components.Argument{

apptrust/commands/application/update_app_cmd.go

@@ -79,6 +79,29 @@ func GetUpdateAppCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.AppUpdate,
 		Description: "Update an existing application",
+		AIDescription: `Update metadata (display name, description, criticality, maturity, labels, owners) of an existing application identified by its key.
+
+When to use:
+- Change display attributes (name, description, criticality, maturity) of an existing application.
+- Add or remove labels, user owners, or group owners.
+
+Prerequisites:
+- The application must already exist (see app-create).
+- Configured server and update permission on the application's project.
+
+Common patterns:
+  $ jf apptrust app-update my-app --desc="Updated description"
+  $ jf apptrust app-update my-app --business-criticality=high --maturity-level=production
+  $ jf apptrust app-update my-app --add-labels="env=prod;tier=critical"
+  $ jf apptrust app-update my-app --remove-labels="env=staging"
+  $ jf apptrust app-update my-app --user-owners="alice;bob" --group-owners="platform-team"
+
+Gotchas:
+- --labels replaces the full label set; --add-labels and --remove-labels modify incrementally.
+- --user-owners and --group-owners replace the full owner list each time they are specified.
+- Application key cannot be changed; use app-delete and app-create if you need a different key.
+
+Related: jf apptrust app-create, jf apptrust app-delete`,
 		Category:    common.CategoryApplication,
 		Aliases:     []string{"au"},
 		Arguments: []components.Argument{

apptrust/commands/package/bind_package_cmd.go

@@ -70,6 +70,29 @@ func GetBindPackageCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.PackageBind,
 		Description: "Bind packages to an application.",
+		AIDescription: `Bind (associate) a specific package version to an existing application so that AppTrust tracks it as part of that application's catalog.
+
+When to use:
+- Declare that a published package version (npm, docker, maven, etc.) belongs to a given application for governance and traceability.
+- Pre-associate packages before creating an application version that includes them.
+
+Prerequisites:
+- The application (application-key) must already exist.
+- The package and version must already exist in Artifactory.
+- Configured server and bind permission on the application's project.
+
+Common patterns:
+  $ jf apptrust package-bind my-app docker my-image 1.0.0
+  $ jf apptrust package-bind my-app npm @scope/my-lib 2.3.1
+  $ jf apptrust package-bind my-app maven com.acme:widget 1.0.0
+  $ jf at pb my-app generic my-bundle 1.0.0 --server-id=my-server
+
+Gotchas:
+- All four positional arguments are required (application-key, package-type, package-name, package-version).
+- package-type must match a package type recognized by Artifactory (e.g., npm, docker, maven, generic).
+- Binding does not move artifacts; it only registers the association.
+
+Related: jf apptrust package-unbind, jf apptrust version-create`,
 		Category:    common.CategoryPackage,
 		Aliases:     []string{"pb"},
 		Arguments: []components.Argument{

apptrust/commands/package/unbind_package_cmd.go

@@ -63,6 +63,26 @@ func GetUnbindPackageCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.PackageUnbind,
 		Description: "Unbind packages from an application.",
+		AIDescription: `Remove a previously created binding between a specific package version and an application.
+
+When to use:
+- Revoke an association between a package version and an application (e.g., the package was bound by mistake or moved to a different application).
+- Clean up bindings before deleting an application.
+
+Prerequisites:
+- The binding must currently exist.
+- Configured server and unbind permission on the application's project.
+
+Common patterns:
+  $ jf apptrust package-unbind my-app docker my-image 1.0.0
+  $ jf apptrust package-unbind my-app npm @scope/my-lib 2.3.1
+  $ jf at pu my-app maven com.acme:widget 1.0.0 --server-id=my-server
+
+Gotchas:
+- All four positional arguments are required and must exactly match the existing binding.
+- Unbinding does not delete the package from Artifactory; only the AppTrust association is removed.
+
+Related: jf apptrust package-bind, jf apptrust app-delete`,
 		Category:    common.CategoryPackage,
 		Aliases:     []string{"pu"},
 		Arguments: []components.Argument{

apptrust/commands/system/ping_cmd.go

@@ -50,6 +50,24 @@ func GetPingCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.Ping,
 		Description: "Ping AppTrust server.",
+		AIDescription: `Send a health-check request to the AppTrust service on the configured JFrog Platform.
+
+When to use:
+- Verify that AppTrust is reachable and the configured credentials authenticate before running other apptrust commands.
+- Quickly diagnose connectivity or auth issues in CI scripts.
+
+Prerequisites:
+- A configured server (jf c add or jf login) or per-command flags --url and either --user/--access-token or --server-id.
+
+Common patterns:
+  $ jf apptrust ping
+  $ jf at p --server-id=my-server
+  $ jf apptrust ping --url=https://my.jfrog.io --access-token=$JFROG_TOKEN
+
+Gotchas:
+- Returns a non-zero exit code if the server is unreachable or credentials are invalid; does not verify per-application permissions.
+
+Related: jf c show, jf rt ping`,
 		Category:    common.CategorySystem,
 		Aliases:     []string{"p"},
 		Arguments:   []components.Argument{},

apptrust/commands/version/create_app_version_cmd.go

@@ -90,6 +90,29 @@ func GetCreateAppVersionCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.VersionCreate,
 		Description: "Create application version.",
+		AIDescription: `Create a new application version from one or more sources (builds, release bundles, other application versions, packages, or artifacts).
+
+When to use:
+- Assemble a new releasable application version from artifacts produced upstream in CI.
+- Create a draft version that can later be finalized via version-update-sources.
+
+Prerequisites:
+- The application (--app-key) must already exist (see app-create).
+- Configured server with AppTrust enabled and write permission on the application's project.
+- At least one source must be provided either via --spec or one of the --source-type-* flags.
+
+Common patterns:
+  $ jf apptrust version-create my-app 1.0.0 --source-type-builds="name=my-build, id=42"
+  $ jf apptrust version-create my-app 1.0.0 --source-type-packages="type=docker, name=my-image, version=1.0.0, repo-key=docker-local"
+  $ jf apptrust version-create my-app 1.0.0 --spec=version-spec.json --spec-vars="BUILD=42"
+  $ jf apptrust version-create my-app 1.0.0 --source-type-builds="name=b, id=1" --draft --dry-run
+
+Gotchas:
+- The version argument must be a valid SemVer string.
+- --spec cannot be combined with --source-type-* flags; choose one approach.
+- --sync defaults to true; pass --sync=false to return as soon as the request is accepted.
+
+Related: jf apptrust version-update-sources, jf apptrust version-promote, jf apptrust version-release`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vc"},
 		Arguments: []components.Argument{

apptrust/commands/version/delete_app_version_cmd.go

@@ -59,6 +59,25 @@ func GetDeleteAppVersionCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.VersionDelete,
 		Description: "Delete application version.",
+		AIDescription: `Permanently delete an application version from the AppTrust service.
+
+When to use:
+- Clean up obsolete or invalid versions (e.g., failed drafts, test versions).
+- Free up names after an incorrect version was created.
+
+Prerequisites:
+- Configured server and delete permission on the application's project.
+- The version should not be actively promoted to stages you cannot reach with delete permissions.
+
+Common patterns:
+  $ jf apptrust version-delete my-app 1.0.0
+  $ jf at vd my-app 0.1.0-rc1 --server-id=my-server
+
+Gotchas:
+- Deletion is irreversible; consider version-rollback first if you only want to undo a promotion.
+- Deleting a released version may be restricted by platform policy.
+
+Related: jf apptrust version-rollback, jf apptrust version-create`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vd"},
 		Arguments: []components.Argument{

apptrust/commands/version/promote_app_version_cmd.go

@@ -102,6 +102,28 @@ func GetPromoteAppVersionCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.VersionPromote,
 		Description: "Promote application version.",
+		AIDescription: `Promote an existing application version to a target stage (e.g., QA, STAGING, PROD), optionally copying or moving its artifacts.
+
+When to use:
+- Advance a tested application version to the next stage in your release lifecycle.
+- Apply additional artifact properties or filter included/excluded repositories during promotion.
+
+Prerequisites:
+- The application version must already exist and be in a state that permits promotion.
+- Configured server and promote permission on the target stage/project.
+
+Common patterns:
+  $ jf apptrust version-promote my-app 1.0.0 QA
+  $ jf apptrust version-promote my-app 1.0.0 PROD --promotion-type=move
+  $ jf apptrust version-promote my-app 1.0.0 STAGING --include-repos="repo-stage-local" --props="env=staging;owner=team"
+  $ jf apptrust version-promote my-app 1.0.0 PROD --overwrite-strategy=fail --dry-run
+
+Gotchas:
+- target-stage is a positional argument and must match a stage defined in your AppTrust configuration.
+- --promotion-type defaults to "copy"; using "move" deletes artifacts from the source repos.
+- --overwrite-strategy controls behavior when target repos already contain artifacts with the same path but different checksum.
+
+Related: jf apptrust version-release, jf apptrust version-rollback, jf apptrust version-create`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vp"},
 		Arguments: []components.Argument{

apptrust/commands/version/release_app_version_cmd.go

@@ -99,6 +99,28 @@ func GetReleaseAppVersionCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.VersionRelease,
 		Description: "Release application version.",
+		AIDescription: `Release an application version, marking it as the final/released artifact set and optionally copying or moving artifacts according to the release configuration.
+
+When to use:
+- Finalize an application version after it has been promoted through earlier stages.
+- Produce the released set of artifacts for downstream consumers.
+
+Prerequisites:
+- The application version must already exist and be eligible for release.
+- Configured server and release permission on the application's project.
+
+Common patterns:
+  $ jf apptrust version-release my-app 1.0.0
+  $ jf apptrust version-release my-app 1.0.0 --promotion-type=move
+  $ jf apptrust version-release my-app 1.0.0 --include-repos="prod-local" --props="released=true"
+  $ jf apptrust version-release my-app 1.0.0 --overwrite-strategy=fail
+
+Gotchas:
+- Release is a one-way transition; use version-rollback to undo promotions but a released version typically cannot be re-released.
+- --promotion-type defaults to "copy".
+- --sync defaults to true; pass --sync=false for asynchronous behavior.
+
+Related: jf apptrust version-promote, jf apptrust version-rollback`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vr"},
 		Arguments: []components.Argument{

apptrust/commands/version/rollback_app_version_cmd.go

@@ -71,6 +71,26 @@ func GetRollbackAppVersionCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.VersionRollback,
 		Description: "Roll back application version promotion.",
+		AIDescription: `Roll back a previous promotion of an application version from a given stage, reverting artifact placement performed by that promotion.
+
+When to use:
+- Undo a recent promotion that introduced regressions or wrong content.
+- Revert a release that needs to be retracted from a stage.
+
+Prerequisites:
+- The application version must currently be promoted to the specified from-stage.
+- Configured server and rollback permission on the application's project.
+
+Common patterns:
+  $ jf apptrust version-rollback my-app 1.0.0 PROD
+  $ jf apptrust version-rollback my-app 1.0.0 STAGING --sync=false
+  $ jf at vrb my-app 1.0.0 QA --server-id=my-server
+
+Gotchas:
+- All three positional arguments (application-key, version, from-stage) are mandatory.
+- Rollback acts on the most recent promotion to from-stage; it does not delete the version itself (use version-delete for that).
+
+Related: jf apptrust version-promote, jf apptrust version-delete`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vrb"},
 		Arguments: []components.Argument{

apptrust/commands/version/update_app_version_cmd.go

@@ -111,6 +111,28 @@ func GetUpdateAppVersionCommand(appContext app.Context) components.Command {
 	return components.Command{
 		Name:        commands.VersionUpdate,
 		Description: "Updates the user-defined annotations (tag and custom key-value properties) for a specified application version.",
+		AIDescription: `Update user-defined annotations on an existing application version: its tag and custom key-value properties. Does not modify sources or stage.
+
+When to use:
+- Attach metadata such as an environment label, release notes URL, or owner to an existing version.
+- Add or remove custom properties without changing the version content.
+
+Prerequisites:
+- The application version must already exist.
+- Configured server and update permission on the application's project.
+
+Common patterns:
+  $ jf apptrust version-update my-app 1.0.0 --tag=stable
+  $ jf apptrust version-update my-app 1.0.0 --properties="env=prod;owner=team-a,team-b"
+  $ jf apptrust version-update my-app 1.0.0 --delete-properties="env,owner"
+  $ jf apptrust version-update my-app 1.0.0 --tag=stable --properties="release-notes=https://example.com/notes"
+
+Gotchas:
+- --properties replaces values for the specified keys; other keys are untouched.
+- --delete-properties takes a comma-separated list of keys and removes those keys entirely.
+- This command does not change sources or promotion stage; use version-update-sources or version-promote for those.
+
+Related: jf apptrust version-update-sources, jf apptrust version-create`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vu"},
 		Arguments: []components.Argument{

apptrust/commands/version/update_app_version_sources_cmd.go

@@ -114,6 +114,29 @@ func GetUpdateAppVersionSourcesCommand(appContext app.Context) components.Comman
 	return components.Command{
 		Name:        commands.VersionUpdateSources,
 		Description: "Updates the sources for a draft application version.",
+		AIDescription: `Add sources (builds, release bundles, application versions, packages, or artifacts) and optional include/exclude filters to a draft application version.
+
+When to use:
+- Incrementally build up the content of a draft application version across multiple CI steps before finalizing.
+- Add late-arriving artifacts to a draft created earlier with version-create --draft.
+
+Prerequisites:
+- The application version must exist and be in draft state.
+- Configured server and update permission on the application's project.
+- At least one --source-type-* flag or a --spec is required.
+
+Common patterns:
+  $ jf apptrust version-update-sources my-app 1.0.0 --source-type-builds="name=integration-build, id=12"
+  $ jf apptrust version-update-sources my-app 1.0.0 --spec=sources.json --spec-vars="ENV=ci"
+  $ jf apptrust version-update-sources my-app 1.0.0 --source-type-packages="type=docker, name=img, version=1, repo-key=docker-local" --dry-run
+  $ jf apptrust version-update-sources my-app 1.0.0 --source-type-artifacts="path=repo/path/file.zip" --fail-fast=false
+
+Gotchas:
+- --spec cannot be combined with --source-type-* flags.
+- --fail-fast defaults to true; with multiple sources, one failure aborts the rest unless disabled.
+- Only applies to draft versions; released or promoted versions reject source changes.
+
+Related: jf apptrust version-create, jf apptrust version-update`,
 		Category:    common.CategoryVersion,
 		Aliases:     []string{"vus"},
 		Arguments: []components.Argument{

cli/cli.go

@@ -18,6 +18,25 @@ func GetJfrogCliApptrustApp() components.App {
 			Name:        "apptrust",
 			Aliases:     []string{"at"},
 			Description: "AppTrust commands.",
+			AIDescription: `JFrog AppTrust commands (alias: at) for managing applications, application versions, and package bindings.
+
+Use this namespace to:
+- Create, update, and delete applications (logical groupings of releasable units identified by an application key).
+- Create application versions from sources (builds, release bundles, application versions, packages, artifacts), promote them through stages, release them, roll back, and delete them.
+- Bind or unbind packages to/from an application.
+- Ping the AppTrust service to verify connectivity.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add or jf login) with AppTrust enabled, or per-command flags --url, --user, --access-token, --server-id.
+- Required permissions on the target project/application for write operations.
+
+Common patterns:
+  $ jf apptrust ping
+  $ jf apptrust app-create my-app --project=default
+  $ jf apptrust version-create my-app 1.0.0 --source-type-builds="name=my-build, id=1"
+  $ jf apptrust version-promote my-app 1.0.0 PROD
+
+Related: jf rt, jf release-bundle commands.`,
 			Category:    "Command Namespaces",
 			Commands: []components.Command{
 				system.GetPingCommand(appContext),