CLI Tools And Portals

Why this matters

As a Platform Engineer, you turn complex platform capabilities into simple, reliable developer workflows. Two high-leverage tools for this are:

• CLI tools: fast, scriptable, discoverable interfaces for everyday tasks.
• Developer portals: a single place for service discovery, templates, self-service operations, and standards.

Strong CLI and portal experiences reduce onboarding time, eliminate fragile copy-paste guides, and make golden paths the easiest paths.

Who this is for

• Platform and infra engineers who enable product teams.
• Backend engineers building internal tooling.
• Tech leads standardizing ways of working.

Prerequisites

• Comfort with a shell (bash, zsh) and basic scripting.
• Familiarity with your platform stack (e.g., containers, CI/CD, cloud or Kubernetes).
• Basic Git and environment management knowledge.

Concept explained simply

A good CLI is like a reliable remote control: clear buttons, predictable responses, and a help screen you can trust. A good developer portal is the living map of your software: what exists, how it’s built, and which path to take next.

Mental model

Think of your platform as a set of powerful but sharp tools. Your CLI and portal are the guards and guides:

• Guardrails: prevent dangerous actions and guide safe defaults.
• Golden paths: pre-approved templates and workflows that solve 80% of cases.
• Discoverability: easy to find the right command, template, or doc without context switching.

Design principles for CLI tools

• Consistent command style: choose noun-verb (service create) or verb-noun (create service) and stick to it.
• Predictable flags: global flags like --help, --version, --verbose, --quiet; command-specific flags after them.
• Great help built-in: dx --help, dx service --help, dx service create --help include examples.
• Safety by default: dry runs (--dry-run), confirmations for destructive actions, idempotent operations.
• Clear errors and exit codes: exit 0 on success; non-zero on failures; actionable messages with next steps.
• Speed and portability: single binary or minimal runtime deps; support auto-complete; cache where safe.
• Auth and audit: integrate SSO or tokens, avoid storing secrets in plain text, log key events (without PII).
• Observability: optional, privacy-safe telemetry (opt-in), structured logs, --trace for deep debug.

Design principles for developer portals

• Single source of truth: catalog of systems, services, data pipelines, and owners.
• Templates and golden paths: opinionated service scaffolding that includes CI/CD, security, and observability.
• Self-service actions: create environments, request credentials, run maintenance tasks with approval flows.
• Scorecards and standards: surface gaps (SLIs/SLOs, alerts, docs, on-call) and guide remediation.
• Auth and RBAC: integrate with SSO, show people only what they should see.
• Integrations: CI/CD, incident systems, runbooks, cost dashboards, docs.

Worked examples

Example 1: A safe service scaffolding CLI

Command family: dx service

Common usage:
  dx service create --name payments-api --template rest-go --owner team-payments --dry-run
  dx service open --name payments-api
  dx service score --name payments-api --output json

Design notes:
- noun-verb style (service create)
- create generates repo, CI/CD, Dockerfile, healthcheck, alerts
- --dry-run prints planned resources; --yes skips confirmation
- dx service score shows portal scorecard results locally

Example 2: Wrapping kubectl safely

Command family: dx k8s

Common usage:
  dx k8s switch --env prod
  dx k8s deploy --service payments-api --image ghcr.io/acme/payments:1.8.2 --dry-run
  dx k8s rollback --service payments-api --to 1.8.1 --yes

Safety features:
- Guardrail: block deploy to prod outside maintenance window unless --override with reason
- Automatic namespace selection per service
- Validations: image exists, service label matches, canary by default

Example 3: Portal golden path template

Template: rest-service-default
Includes:
- Repo boilerplate with license, README, codeowners
- CI: build, test, lint, image push, SBOM
- CD: canary rollout with automatic rollback on SLO breach
- Observability: metrics, tracing, dashboard template, alert rules
- Security: container scanning gate, dependency scan

Example 4: Scorecard categories

Categories & checks:
- Operability: on-call rotation set, runbook linked, SLO defined
- Security: secrets via vault, image scanning passing, least-privilege IAM
- Reliability: healthcheck endpoint, readiness/liveness probes, error budget policy
- Documentation: README complete, ADRs present, API docs linked

Step-by-step: Build a minimal CLI command

1. Pick one task to automate (e.g., create a service repo).
2. Write the command spec: name, flags, inputs, outputs, side effects.
3. Add safety: --dry-run, confirmation prompt, rollback note.
4. Implement a thin wrapper in your preferred language or shell.
5. Add dx ... --help with at least two examples.
6. Package it (single binary or simple install script) and add autocomplete.
7. Pilot with 2–3 developers; iterate on confusing parts.

Name: dx service create
Inputs: --name, --template, --owner, --dry-run, --yes
Outputs: repo URL, CI/CD link, dashboard link
Side effects: creates repo, pipelines, alert rules
Errors: name exists, invalid template, missing owner

Exercises

Do these to solidify your understanding. You can complete them in a text editor or shell. Hints and sample solutions are expandable below.

Exercise ex1 — Design a cohesive CLI for service scaffolding

Create a CLI spec for service creation and lifecycle. Include usage, subcommands, flags, examples, safety, exit codes, and help text snippets.

Exercise ex2 — Draft a Developer Portal template and scorecard

Write a minimal template metadata and a scorecard with 5 checks. Include owners, tags, and required parameters for scaffolding.

Common mistakes and how to self-check

• Too many flags, unclear defaults: run dx ... --help and see if a newcomer would understand.
• No safe mode for prod: ensure --dry-run and confirm prompts exist; test a rollback path.
• Portal sprawl without ownership: every service should have an owner and escalation path.
• Hidden tribal knowledge: move steps from wikis into CLI commands or portal actions.
• Inconsistent naming: verify subcommands and flags follow one pattern across the CLI.

Practical projects

• Build a single-binary CLI that scaffolds a service and prints a local scorecard.
• Create a golden path template that provisions CI/CD, alerts, and dashboards.
• Add a portal action to rotate credentials with approval and audit logging.

Learning path

• Start: design the CLI surface (spec, help, examples).
• Next: implement one end-to-end golden path template.
• Then: integrate scorecards and make them visible in both CLI and portal.
• Finally: add self-service actions with guardrails and audits.

Next steps

• Finish the exercises and mini challenge.
• Pilot with a small team and collect feedback.
• Iterate on help messages and defaults based on real usage.

Mini challenge

In one page, define how a developer creates a new API with auth, CI/CD, and monitoring using only your CLI and portal. Include commands, expected outputs, and what they see in the portal after 10 minutes.

Quick Test

Everyone can take the test for free. Only logged-in users will have their progress saved.