Based on Primer CLI Design Guidelines | Verified against Moderne CLI 4.1.6 + cli-reference.md | April 2026
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.
| 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 |
| 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. |
| 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. |
| 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 |
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.
# 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
# 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
```# 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"