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

The following table lists command arguments.

Options

This command has no flags.

Environment Variables

The following table lists the environment variable.

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 no platform URL is in config, jf gsm fails with an error of this form (the CLI logs it as an [Error]):

failed to get server URL or major version: error extracting server details: no JFrog Platform URL specified, either via the --url flag or as part of the server configuration. This means markdown URLs will be invalid

How Command Summaries Work

The JFrog CLI uses a 2-phase approach for command summaries. While you run 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, and you do not need extra flags.

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.

You must set JFROG_CLI_COMMAND_SUMMARY_OUTPUT_DIR before you run 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-repository/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 continuous integration and delivery (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 pull request 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 you run 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 you run 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-repository
└── <a href='https://example.jfrog.io/ui/repos/tree/General/my-repository/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.