Moderne CLI: Optimizing -h Messages for Humans + Agents

Based on Primer CLI Design Guidelines | Verified against Moderne CLI 4.1.6 + cli-reference.md | April 2026

cli-reference.md — Quick Reference Preamble

Added to the top of the existing CLI reference doc. Agents read this once at session start to understand the full command landscape. Humans get a scannable overview before the detailed per-command docs.

Setup (run in order)

Step	Command	Purpose	Required?
1	mod config moderne edit <url>	Connect to Moderne tenant.	Yes
2	mod config moderne login	Authenticate (opens browser).	Yes
3	mod config http trust-store edit	SSL trust store for HTTPS.	If corporate proxy or internal CA.
4	mod config recipes artifacts artifactory add <url>	Recipe artifact repository.	If using internal Artifactory.
5	mod config lsts artifacts artifactory add <url>	LST artifact repository.	If publishing LSTs.
6	mod config build maven settings edit <path>	Maven settings.xml.	If custom mirrors or proxies.
7	mod config recipes moderne sync	Download recipes from Moderne.	Yes

Core commands

Command	Purpose
mod build <path>	Build LSTs for repositories. Run before mod run.
mod run <path> --recipe <name>	Run a recipe on pre-built LSTs. Results stored, not applied to files.
mod publish <path>	Publish LST artifacts to Moderne for ingestion.
mod list	List repositories available for building and publishing.
mod exec <path> <cmd>	Run a shell command across repositories.

PR workflow (after running a recipe)

mod run . --recipe <name> # 1. Run recipe mod git apply . --last-recipe-run # 2. Apply changes to files mod git checkout . -b <branch-name> # 3. Create branch mod git add . --last-recipe-run # 4. Stage changes mod git commit . -m "<message>" # 5. Commit mod git push . -u origin <branch-name> # 6. Push to remote

Diagnostics

Command	Purpose
mod config moderne show	Check tenant configuration.
mod config http trust-store show	Check trust store configuration.
mod config recipes list	List installed recipes.
mod config recipes search <query>	Search for a recipe by name.
mod run-history	Show past recipe runs.
mod git status <path>	Check git status across repos.

Common errors and fixes

Error	Fix
PKIX path building failed	mod config http trust-store edit file <path>
No Moderne tenant configured	mod config moderne edit <url>
No recipes available to run	mod config recipes moderne sync
401 Unauthorized (Artifactory)	mod config recipes artifacts artifactory add <url>
Could not resolve dependencies	mod config build maven settings edit <path>
Recipe not found: <name>	mod config recipes moderne sync

Bundled Docs Concept

Markdown files that ship alongside the CLI binary. Agents and humans can reference these locally without network access. Installed to ~/.moderne/docs/ on first run.

TROUBLESHOOTING.md

~/.moderne/docs/TROUBLESHOOTING.md

# Moderne CLI Troubleshooting

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| PKIX path building failed | Missing trust store | `mod config http trust-store edit file <path>` |
| No Moderne tenant configured | Step 1 not done | `mod config moderne edit <url>` |
| No recipes available to run | Recipes not synced | `mod config recipes moderne sync` |
| 401 Unauthorized | Bad Artifactory creds | Re-run `mod config recipes artifacts artifactory add` |
| Could not resolve dependencies | Missing Maven settings | `mod config build maven settings edit <path>` |
| Recipe not found | Stale catalog | `mod config recipes moderne sync` |

## Diagnostic Commands

```
mod config moderne show          # Check tenant config
mod config http trust-store show # Check SSL setup
mod config recipes list          # List installed recipes
mod config recipes search <q>   # Search recipes by name
mod run-history                  # Show past recipe runs
```

## Escalation Contacts

If the above doesn't resolve your issue:

- **Platform team**: Check your org's internal wiki or Slack channel
- **Moderne support**: https://docs.moderne.io/support
- **Config contact**: See CONFIG-TEMPLATE.yaml for org-specific contacts

SETUP-CHECKLIST.md

~/.moderne/docs/SETUP-CHECKLIST.md

# Moderne CLI Setup Checklist

## Required

- [ ] 1. Connect to tenant
      `mod config moderne edit <tenant-url>`
      Verify: `mod config moderne show`

- [ ] 2. Log in
      `mod config moderne login`
      Verify: `mod config moderne show`

- [ ] 7. Sync recipes
      `mod config recipes moderne sync`
      Verify: `mod config recipes list`

## Conditional (ask your platform team)

- [ ] 3. Trust store (if corporate proxy / internal CA)
      `mod config http trust-store edit file <path>`

- [ ] 4. Recipe repo (if internal Artifactory)
      `mod config recipes artifacts artifactory add <url>`

- [ ] 5. LST repo (if publishing LSTs)
      `mod config lsts artifacts artifactory add <url>`

- [ ] 6. Maven settings (if custom mirrors/proxies)
      `mod config build maven settings edit <path>`

## Verify Everything

```
mod config moderne show
mod config http trust-store show
mod config recipes list
```

CONFIG-TEMPLATE.yaml

~/.moderne/docs/CONFIG-TEMPLATE.yaml

# Moderne CLI Configuration Template
# Copy this file and fill in your org's values.
# Distribute to your team so they can set up the CLI quickly.

tenant:
  url: https://app.moderne.io          # Your Moderne tenant URL
  # api: https://api.app.moderne.io    # Auto-detected from tenant URL

trust_store:
  # path: /etc/pki/java/cacerts        # Uncomment if behind corporate proxy
  # password: changeit

artifacts:
  recipes:
    # url: https://artifactory.corp.com/moderne-recipes
    # auth: jfrog-api-token             # or user+password
  lsts:
    # url: https://artifactory.corp.com/moderne-lsts
    # auth: jfrog-api-token

maven:
  # settings: ~/.m2/settings.xml        # Uncomment if custom mirrors

# Team contacts for CLI support
contacts:
  platform_team: platform-eng@corp.com
  security_team: security@corp.com
  moderne_admin: admin@corp.com
  slack_channel: "#moderne-help"