Midtrans CLI

Sandbox only. v0.1 refuses production Midtrans hosts and production-enabled manifests. Classic server keys must also have Midtrans's Sandbox SB- prefix. BI-SNAP credentials do not encode their environment, so operators must provide Sandbox credentials only.

The proposed first release is under internal review. See Midtrans CLI v0.1.0 internal release review for its scope, evidence, blockers, and approval checklist. No v0.1.0 tag or public release exists yet.

Skill reasons; CLI proves. The official Midtrans Agent Skill can decide what an integration needs, while this CLI provides deterministic repository inspection, sandbox execution, and checksummed evidence. The CLI never writes application code. It may initialize its own .midtrans/ configuration and evidence files, but changes to merchant application code remain under the merchant or agent host's control.

Local development quick start

The development installer builds, verifies, and atomically installs a regular midtrans binary for the current user at ${MIDTRANS_INSTALL_DIR:-$HOME/.local/bin}. It does not require sudo, create a source symlink, or edit a shell profile.

tools/install-local.sh
cd /path/to/merchant
midtrans init
midtrans setup
midtrans status
midtrans test checkout --amount 10000
midtrans test webhook
midtrans verify

Machine-readable agent handshake

An Agent Skill must complete this handshake before using the CLI:

midtrans agent capabilities --json --non-interactive
midtrans agent inspect --json --non-interactive
midtrans agent check --product snap --json --non-interactive

Release artifact verification

The v0.1.0 release artifacts are checksummed but unsigned. Official Midtrans release documentation publishes the immutable download URL for each version.

1. Follow only the download URL published by official Midtrans documentation.

2. Download the archive for your operating system and architecture together with checksums.txt from the same immutable version directory.

3. Verify the archive against the checksum manifest:

   archive=midtrans-cli_0.1.0_darwin_arm64.tar.gz
   awk -v archive="$archive" '$2 == archive { print }' checksums.txt | sha256sum -c -
   # macOS:
   awk -v archive="$archive" '$2 == archive { print }' checksums.txt | shasum -a 256 -c -

4. Extract the archive and place midtrans on your PATH.

5. Run midtrans agent capabilities --json --non-interactive and confirm the expected schema, capabilities, and journeys before an agent uses it.

Checksums detect corruption or accidental modification after publication, but they do not authenticate the publisher as a signature would. Artifact signing is deferred beyond v0.1.0. The hosted install.sh remains unpublished; do not use an unverified curl | sh installer. Distribution is limited to the checksummed but unsigned archives linked from official Midtrans documentation. Homebrew and npm launchers are deferred until Midtrans separately approves, provisions, and evaluates those channels.

Sandbox workflow

Commands emit the stable result-schema v1 JSON contract when both --json and --non-interactive are supplied. Replace /path/to/merchant and example values with sandbox-only inputs.

midtrans init --project-dir /path/to/merchant --json --non-interactive
midtrans setup --project-dir /path/to/merchant --json --non-interactive
midtrans status --project-dir /path/to/merchant --json --non-interactive
midtrans test checkout --amount 10000 --project-dir /path/to/merchant --json --non-interactive
midtrans test webhook --order-id <reference> --amount 10000 --project-dir /path/to/merchant --json --non-interactive
midtrans verify --project-dir /path/to/merchant --json --non-interactive

Review and edit .midtrans/manifest.yaml yourself. It contains credential references, never secret values. References may use env:NAME or a project-relative file:./path; credential files must remain inside the project, must not resolve through a symlink outside it, and must have owner-only permissions. v0.1 remains Sandbox-only: the CLI rejects production Midtrans hosts and production-enabled manifests, and validates the Sandbox prefix on classic server keys.

midtrans init now creates a neutral hybrid manifest with sandbox-only policy, loopback-safe application state defaults, and empty credential_sets, integrations, routing, and verification.required. midtrans setup is the entry point that adds the first Snap-oriented credential set, integration, checkout routing, and verification requirements.

Representative multi-product fixtures

The repository also ships synthetic loopback fixtures for representative multi-product merchant flows under evaluations/fixtures/:

• hybrid-snap-gopay
• coreapi-paymentlink
• bisnap-qris-va

These fixtures contain clean hybrid manifests, synthetic placeholder credentials, loopback-only stubs, and checked-in rehearsal steps for pack list, agent plan, agent run, agent resume, reconciliation, and evidence export. They do not claim live Sandbox success. Real Sandbox prerequisites such as activation, buyer interaction, callback delivery, or device proof stay blocked and must remain explicit in any evaluation report.

Contracts and compatibility

• Capability contract
• Result schema
• Manifest schema
• Evidence schema
• Agent Skill compatibility

These public contracts cover the compiled multi-product CLI surface: Snap, Core API, Payment Link, BI-SNAP, GoPay tokenization, and Subscription. Production execution, framework code generation, telemetry, and remote MCP operation stay outside the current boundary.

Development gates

./tools/check_release.sh
go run github.com/goreleaser/goreleaser/v2@v2.17.0 build --snapshot --clean

The public-source gate fetches the canonical Markdown form of every docs.midtrans.com URL compiled into the Snap, Core API, Payment Link, BI-SNAP, GoPay tokenization, and Subscription packs. It refuses redirects, times out each request attempt after 10 seconds, retries transport interruptions up to three total attempts, and caps each response at 2 MiB. HTTP errors, redirects, and policy violations remain immediate failures. Before hashing, it normalizes CRLF, removes the exact Midtrans Markdown delivery preamble (updatedAt plus the llms.txt discovery notice), and canonicalizes any randomized Cloudflare email-protection attribute or href token by decoding its value. A mismatch reports source IDs without response bodies and requires deliberate human review before baseline regeneration.

No tag or release should be created until the controlled 18-run evaluation in evaluations/README.md passes its release gate.