Generate a CLI command summary in Markdown

The jf generate-summary-markdown command (jf gsm) compiles recorded JFrog CLI activity into a single Markdown report. The file is written to <JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR>/jfrog-command-summary/markdown.md after you set the output directory and run the commands you want summarized.

Synopsis

jf generate-summary-markdown

Aliases: jf gsm

Arguments

Options

This command has no flags.

Environment Variables

Prerequisites

To satisfy configuration requirements for jf gsm:

1. Ensure your JFrog server is configured with a JFrog Platform URL (not just the Artifactory URL). jf gsm needs the Platform URL to generate correct links in the report.
2. Run jf config show and verify the JFrog Platform URL field is present:

JFrog Platform URL:  https://<your-instance>.jfrog.io/

3. If the field is missing, re-add your server using jf config add:

jf config add <server-id> \
  --url="https://<platform-host>" \
  --user="<username>" \
  --password="<password>" \
  --interactive=false

Where:

• <server-id> — Short name for this configuration (for example acme).
• <platform-host> — JFrog Platform host without a trailing path (for example acme.jfrog.io).
• <username> and <password> — Credentials with permission to use the CLI against that platform.

Example:

jf config add acme \
  --url="https://acme.jfrog.io" \
  --user="[email protected]" \
  --password="your-secret" \
  --interactive=false

If you omit --url, jf gsm exits with:

[Error] failed to get server URL or major version: no JFrog Platform URL specified

How It Works

To understand how command summaries are recorded and compiled:

The JFrog CLI uses a two-phase approach for command summaries:

1. Record: While running CLI commands (such as jf rt upload or jf rt build-publish), the CLI automatically writes summary data to JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR. This recording happens during normal command execution — no extra flags are needed.
2. Compile: After your commands have run, jf gsm reads the recorded data and compiles it into a single Markdown report at <JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR>/jfrog-command-summary/markdown.md.

JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR must be set before running the commands you want to capture.

Examples

Generate a Command Summary

To record CLI usage and produce a Markdown summary:

1. Create and set the output directory:

mkdir -p /tmp/cli-summary
export JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR=/tmp/cli-summary

2. Run your JFrog CLI commands (summary data is recorded automatically):

jf rt upload ./my-artifact.zip my-repo/my-artifact.zip

3. Generate the Markdown summary:

jf gsm

4. Open the report:

cat /tmp/cli-summary/jfrog-command-summary/markdown.md

Use a Custom Output Directory

To write the summary under a project-relative directory:

1. Run:

mkdir -p ./docs/usage
JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR=./docs/usage jf gsm

When to Use

Use jf gsm in CI/CD pipelines to generate a human-readable summary of all CLI commands run during a build. Common scenarios:

• Build reports: Attach the Markdown summary as a build artifact for auditing
• Pull request comments: Post the summary as a PR comment to show what was built and deployed
• Documentation: Track CLI usage patterns across builds

Important Notes

• The JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR environment variable must be set before running any JFrog CLI commands you want to capture. The CLI records command summaries to this directory during execution, and jf gsm compiles them.
• The output directory must exist before running any CLI commands — create it with mkdir -p <DIR>. The CLI does not create the root directory automatically.
• If no commands were recorded before running jf gsm, the command exits successfully but produces no report file.
• If a previous CLI command failed mid-run, it may leave an empty data file in the output directory. If jf gsm prints [Warn] Failed to generate markdown for section: … unexpected end of JSON input, check for and remove zero-byte *-data files under <DIR>/jfrog-command-summary/.

Expected Output

The command writes a Markdown file to <JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR>/jfrog-command-summary/markdown.md. The content format depends on which commands were recorded. For example, after an upload command the report contains an HTML tree of the uploaded artifacts with links to the JFrog UI:

<pre>

📦 my-repo
└── <a href='https://example.jfrog.io/ui/repos/tree/General/my-repo/my-artifact.zip' target="_blank">my-artifact.zip</a>

</pre>

Each command category (upload, build-info, security, evidence) generates its own section in the report.