1111111                  AAA               MMMMMMMM               MMMMMMMM
 1::::::1                 A:::A              M:::::::M             M:::::::M
1:::::::1                A:::::A             M::::::::M           M::::::::M
111:::::1               A:::::::A            M:::::::::M         M:::::::::M
   1::::1              A:::::::::A           M::::::::::M       M::::::::::M
   1::::1             A:::::A:::::A          M:::::::::::M     M:::::::::::M
   1::::1            A:::::A A:::::A         M:::::::M::::M   M::::M:::::::M
   1::::l           A:::::A   A:::::A        M::::::M M::::M M::::M M::::::M
   1::::l          A:::::A     A:::::A       M::::::M  M::::M::::M  M::::::M
   1::::l         A:::::AAAAAAAAA:::::A      M::::::M   M:::::::M   M::::::M
   1::::l        A:::::::::::::::::::::A     M::::::M    M:::::M    M::::::M
   1::::l       A:::::AAAAAAAAAAAAA:::::A    M::::::M     MMMMM     M::::::M
111::::::111   A:::::A             A:::::A   M::::::M               M::::::M
1::::::::::1  A:::::A               A:::::A  M::::::M               M::::::M
1::::::::::1 A:::::A                 A:::::A M::::::M               M::::::M
111111111111AAAAAAA                   AAAAAAAMMMMMMMM               MMMMMMMM

What This Is

1am is the command-line entrypoint for the 1AM Midnight developer experience. It is built to help developers and AI coding agents go from an empty folder to a working Midnight application with the right structure, contract workflow, wallet conventions, 1AM brand system, and Explorer API access already in place.

The CLI is intentionally shaped like other production developer tools: install it globally with npm, run 1am --help, scaffold a project, compile contracts, bundle proof assets, deploy through the 1AM proof server, and query live Explorer data without manually copying boilerplate between repos.

npm install -g oneam
1am --help

Why We Built It

Midnight app development currently involves a lot of repeated setup: Compact contracts, proving keys, wallet integration, proof-server configuration, app templates, Explorer lookup, and AI instructions all have to line up. 1AM CLI packages those conventions into one repeatable workflow.

The goal is simple: make it easy for a human developer or an AI agent to start building a Midnight app in the 1AM ecosystem quickly, correctly, and with fewer fragile copy-paste steps.

What We Studied And Integrated

This repository was built after studying the existing 1AM and Midnight application surface:

• one-am-wallet informed the wallet integration direction, public key derivation, seed handling, and the preferred window.midnight["1am"] connector path.
• The Midnight swap / zk mint app work informed lightweight app scaffolding, proof asset hosting, and practical Midnight DApp wiring.
• The Dominion Poker contract work informed the one-command compile and deploy flow, including ProofStation-style proving and network confirmation.
• The 1AM repo deployment setup informed the deploy command and repo-local developer ergonomics.
• create-mn-app informed the official Midnight scaffold compatibility surface.
• Official Midnight examples such as counter and bulletin board informed template expectations and Compact project structure.
• 1am-explorer supplied the 1AM design language, typography rules, brand assets, theme tokens, and Explorer API references.
• The 1AM starter template informed the minimal app shape and AI-readable project overlays.

Current Feature Set

1AM CLI currently provides these top-level capabilities:

• 1am scaffold creates bundled 1AM templates or official Midnight templates with a 1AM overlay.
• 1am compile compiles Compact contracts into a stable local output directory.
• 1am deploy compiles, proves, signs, submits, and waits for Midnight network confirmation.
• 1am proof bundle copies compiled proving assets into frontend-friendly public directories.
• 1am wallet info derives preview, preprod, and mainnet wallet details from a seed or mnemonic.
• 1am wallet create agent --set-default creates an encrypted local agent wallet profile.
• 1am wallet sync agent --network preprod --background keeps a stored wallet synced in the background.
• 1am wallet stop agent --network preprod stops a recorded background wallet sync.
• 1am deploy ... --wallet agent deploys with a stored wallet instead of copying seeds into shell history.
• 1am explorer queries the 1AM Explorer API for network, transaction, block, contract, search, and recent transaction data.
• 1am skills install installs 1AM AI skills into a repository.
• 1am design install installs the 1AM design skill and Explorer-derived brand kit.
• 1am doctor checks required local tools and 1AM service health.
• 1am art prints the compact 1AM ASCII wordmark.

Install

Install globally:

npm install -g oneam
1am --help

Use without global install:

npx oneam@latest --help

Run from source:

npm install
npm run build
node dist/index.js --help

The package exposes the binary through package.json:

{
  "bin": {
    "1am": "dist/index.js"
  }
}

This is the standard npm CLI shipping path. On macOS and Linux, npm links 1am into the global npm bin directory. On Windows, npm creates the command shim automatically.

Quickstart

Create a 1AM starter app:

1am scaffold starter ./night-app
cd night-app
npm install
npm run contract:prepare
npm run build

Create from an official Midnight counter scaffold:

1am scaffold counter ./counter-app
cd counter-app
npm install

Compile a contract:

1am compile ./contracts/counter/src/counter.compact --out ./.1am/compiled/counter --force

Bundle proof assets for a frontend:

1am proof bundle ./.1am/compiled/counter ./apps/web/public/contract/compiled/counter --force

Deploy a contract:

1am deploy ./contracts/counter/src/counter.compact --seed "$MIDNIGHT_SEED" --network preprod

Query the Explorer API:

1am explorer summary
1am explorer tx <hash> --network preprod
1am explorer block <height> --network preview

Command Reference

1am scaffold

Scaffolds a project into a target directory.

1am scaffold <template> [targetDir] [options]

Supported template names:

• starter generates the bundled 1AM starter repo with a web app, Compact contract package, wallet overlay, skills, and brand references.
• contract generates a standalone Compact contract package.
• skill installs the 1AM AI skill structure.
• hello-world scaffolds the official Midnight Hello World template and applies the 1AM overlay.
• counter scaffolds the official Midnight counter DApp and applies the 1AM overlay.
• bboard scaffolds the official Midnight bulletin board DApp and applies the 1AM overlay.

Useful options:

--name <name>
--contract-name <contractName>
--force

Example:

1am scaffold starter ./my-1am-app --name my-1am-app --contract-name counter

1am compile

Compiles a .compact contract into a stable local output directory.

1am compile <contractFile> [options]

Useful options:

--name <contractName>
--compiler-version <version>
--out <outDir>
--force
--json

Example:

1am compile ./contracts/counter/src/counter.compact --out ./.1am/compiled/counter --force

Output includes the contract artifacts, compiler metadata, proving keys, and ZKIR files needed by downstream app or deploy flows.

1am proof bundle

Copies compiled proving assets into a frontend-safe public directory.

1am proof bundle <compiledDir> [outputDir] [options]

Example:

1am proof bundle ./.1am/compiled/counter ./apps/web/public/contract/compiled/counter --force

This is useful when a web app uses FetchZkConfigProvider or a similar provider to load proving assets from a public path.

1am deploy

Compiles and deploys a Compact contract using local signing plus a ProofStation-compatible proof server.

1am deploy <contractFile> [options]

Important options:

--network <preview|preprod|mainnet>
--seed <seedHex>
--mnemonic <mnemonic>
--seed-env <envVar>
--proof-server <url>
--indexer <url>
--indexer-ws <url>
--rpc <url>
--api-key <key>
--args-json <json>
--private-state-id <id>
--json

Do not hardcode ProofStation API keys. If your proof server requires authentication, request a key from [email protected] and pass it with --api-key or PROOFSTATION_API_KEY.

What the deploy flow does:

• Compiles the Compact source.
• Builds the deploy transaction locally with Midnight SDK packages.
• Uses a local seed or mnemonic for signing.
• Sends proving/finalization work through a ProofStation-compatible /balance-only flow.
• Submits finalized transaction bytes through a Midnight node WebSocket.
• Waits for confirmation through the target network indexer.
• Returns the contract address, ledger transaction identifier, transaction hash, block height, and network id when available.

The deploy flow was corrected to avoid relying on dead /balance-and-submit behavior. The CLI now submits finalized transactions through the Midnight node WebSocket and watches indexer confirmation directly.

1am wallet info

Derives wallet metadata from a seed or mnemonic.

1am wallet info --seed "$MIDNIGHT_SEED" --json

The command returns:

• Coin public key.
• Encryption public key.
• Dust public key.
• Preview shielded address.
• Preprod shielded address.
• Mainnet shielded address.
• Preview unshielded address.
• Preprod unshielded address.
• Mainnet unshielded address.
• Preview dust address.
• Preprod dust address.
• Mainnet dust address.

This helps developers confirm that they are funding and deploying from the expected Midnight identity before sending transactions.

1am wallet create/import/list/show/use/export/sync/stop

Creates and manages local 1AM CLI wallet profiles for humans and agents.

export ONE_AM_WALLET_PASSWORD="replace-with-a-strong-local-password"
1am wallet create agent --set-default
1am wallet sync agent --network preprod
1am wallet sync agent --network preprod --background --interval 60
1am wallet stop agent --network preprod
1am deploy ./contracts/counter/src/counter.compact --wallet agent --network preprod

Wallet profiles are stored under ~/.1am/wallets. Encrypted storage is the default. Disposable local agents can use --insecure-plain, but funded wallets should always use ONE_AM_WALLET_PASSWORD, --password, or --password-env.

The sync command uses the Midnight wallet SDK unshielded wallet runtime against the selected network indexer. It records serialized wallet state, transaction history, balances, available coin count, pending coin count, and background sync process metadata.

1am explorer

Queries the public 1AM Explorer API.

1am explorer summary
1am explorer summary --network preprod
1am explorer tx <hash> --network preprod
1am explorer block <height> --network preview
1am explorer contract <address> --network mainnet
1am explorer search <query> --network mainnet
1am explorer recent-transactions --limit 20 --network mainnet

Network-aware commands:

• summary
• tx
• block
• contract
• search
• recent-transactions

Supported networks:

• mainnet
• preprod
• preview

Mainnet metric helper commands:

• latest-block
• block-time
• blocks-produced
• uptime
• epoch
• d-parameter
• night-supply
• address-activity

The CLI calls /api/v1/{network}/... for network-aware commands. It also validates Explorer responses and reports ok: false if an API route returns HTML instead of JSON, which helps catch stale Vercel rewrites or missing public API routes.

1am skills install

Installs repo-local AI skill files.

1am skills install .

Installed skill content includes:

• 1AM Midnight app guidance.
• Explorer API reference.
• Wallet integration reference.
• DApp connector reference.
• Deploy flow reference.
• ZK key hosting reference.
• 1AM design skill.

This is meant to help AI coding agents build inside a scaffolded repo without losing the conventions that make 1AM apps consistent.

1am design install

Installs 1AM brand and design references.

1am design install .

Installed assets include:

• .codex/skills/1am-design
• .1am/brand/1am-explorer-design-spec.md
• .1am/brand/1am-explorer-theme.css
• .1am/brand/logo-1am.svg
• .1am/brand/logo-1am-explorer.svg

The design skill was copied from the live 1AM Explorer visual language. It documents the typography, color tokens, layout rules, surface treatment, copy chips, detail rows, technical data display, and visual anti-patterns for 1AM-branded apps.

1am doctor

Checks local CLI dependencies and service health.

1am doctor
1am doctor --json

The command checks tools such as:

• Node.js
• npm
• Git
• Docker
• compact
• compactc
• zkir

It also checks configured 1AM service health endpoints for preview, preprod, and compiler services.

1am art

Prints the compact 1AM ASCII wordmark.

1am art

Templates And Overlays

The CLI supports both bundled templates and official Midnight templates.

Bundled templates:

• starter: Minimal 1AM app with web app, contract package, wallet helper, proof bundling path, brand assets, and AI-readable repo instructions.
• contract: Standalone Compact contract package for quickly starting local contract development.
• skill: 1AM AI skill structure for repositories that only need repo-local guidance.

Official Midnight templates with 1AM overlay:

• hello-world
• counter
• bboard

The 1AM overlay adds:

• 1AM.md project guidance.
• Wallet integration docs.
• Preferred 1AM wallet connector path.
• Proof server defaults.
• Explorer references.
• 1AM skills.
• 1AM brand/design references.

1AM Starter App Shape

The bundled starter is intentionally small and AI-friendly. It avoids overly clever abstractions and keeps contract, web, wallet, and proof asset paths easy to inspect.

Typical generated structure:

my-app/
  1AM.md
  .env.example
  package.json
  apps/
    web/
      app/
      lib/
      public/
  contracts/
    counter/
      src/
        counter.compact

The generated root scripts are designed to support the normal loop:

npm run contract:prepare
npm run build

AI Skills

The CLI includes repo-local skills so AI agents can work with the correct context.

The 1AM Midnight skill covers:

• How to scaffold and extend 1AM Midnight apps.
• Wallet integration expectations.
• Explorer API usage.
• Proof asset hosting.
• Deploy flow assumptions.
• DApp connector references.

The 1AM design skill covers:

• Explorer-derived product design language.
• Typography and color tokens.
• Dense chain-data UI rules.
• 1AM logo usage.
• Technical display components.
• Anti-patterns to avoid.

Explorer API Integration

The Explorer API base URL is:

https://explorer.1am.xyz

Network-aware API routes:

GET /api/v1/{network}/summary
GET /api/v1/{network}/transaction?hash=...
GET /api/v1/{network}/block?height=...
GET /api/v1/{network}/contract?address=...
GET /api/v1/{network}/search?q=...
GET /api/v1/{network}/recent-transactions?limit=20

Supported {network} values:

mainnet
preprod
preview

Backwards-compatible mainnet aliases remain supported under /api/v1/mainnet/*.

Validation note: the CLI live Explorer gate verifies JSON responses for mainnet, preprod, and preview. If the Explorer deployment ever falls through to the web app HTML shell, 1am explorer ... --json reports ok: false with the response content type so the routing issue is visible to agents and CI.

End-To-End Flow Tested

The CLI was tested through a real Midnight-style flow:

• Scaffolded a starter app.
• Modified the starter contract into a simple crowd-style contract.
• Compiled the Compact contract.
• Bundled proving assets.
• Deployed to preprod using local signing and ProofStation-compatible proving.
• Submitted through the Midnight node WebSocket.
• Confirmed the transaction through the preprod indexer.
• Documented the flow in docs/e2e-crowd-flow.md.

Recorded preprod result from the E2E deployment:

contract:   5ecd2740d1912a752995a8fa9e0d2945057c2901371bd9ea96d47f0c9adb1584
identifier: 007de00b9f7be147a149532b6ec6bbcfebf2df4cd896c5d45964e4c85d9d26c24a
hash:       330d6ad326a1564721a201403f5ace1a051eb5ec318d4551a1ddefdf20178c27
block:      512336
status:     SUCCESS
network:    preprod

Verification

Core verification commands:

npm run lint
npm run typecheck
npm run build
npm run verify
npm test
npm run release:check
npm run production:check
npm pack --dry-run
npm run smoke:global

What is currently covered:

• TypeScript compilation.
• ESLint.
• CLI build.
• 1am --help.
• 1am art.
• Deterministic wallet lifecycle tests.
• Deterministic CLI E2E tests.
• Encrypted wallet generation.
• Preview, preprod, and mainnet shielded, unshielded, and dust address derivation.
• Wallet list/show/info/use/export behavior.
• Wrong-password and secret-export guardrails.
• Plain throwaway wallet import.
• Stale background sync stop behavior.
• Clean JSON output for compile --json and proof bundle --json.
• Network-aware explorer command routing for mainnet, preprod, and preview against a local fixture.
• Bundled scaffold entrypoints.
• npm package dry-run.
• Isolated global install smoke test.
• Starter scaffold.
• Starter npm install.
• Starter contract compile.
• Proof bundle.
• Starter web build.
• Cross-platform CI on Ubuntu, macOS, and Windows.

Live production gates:

• npm run test:live:wallet-sync checks wallet sync on preview, preprod, and mainnet.
• npm run test:live:scaffold checks official upstream scaffolds: hello-world, counter, and bboard.
• npm run test:live:explorer checks public Explorer API JSON routing on mainnet, preprod, and preview.
• npm run test:live:wallet-tx:required runs real stored-wallet deploy transaction tests. Preview/preprod can use disposable seeds because the 1AM proof server balances the deploy transaction.
• Mainnet transaction tests are intentionally blocked unless ALLOW_MAINNET_TX=1.
• npm run production:check runs deterministic release checks plus the live ecosystem checks.
• Full release criteria are documented in Production Readiness.

CI And Release

The repository includes GitHub Actions workflows:

• .github/workflows/cli-smoke.yml runs verification, deterministic tests, and global install smoke tests on Ubuntu, macOS, and Windows.
• .github/workflows/publish.yml runs the deterministic release gate and publishes to npm with provenance when run manually or when a GitHub release is published.
• .github/workflows/wallet-live-readiness.yml manually runs live wallet sync, official scaffold checks, live Explorer API checks, and gated transaction tests.

The package is prepared for public npm publication:

• Package name: oneam
• Binary name: 1am
• Access: public
• License: MIT
• Node engine: >=20
• Author: UVROXX <[email protected]>
• Homepage: https://1am.xyz
• Funding / builder link: https://webisoft.com

Dry-run publish:

npm publish --dry-run --access public

Actual publish:

npm publish --access public

If trusted publishing is configured in npm, the GitHub release workflow can publish with provenance.

Repository Layout

.
  .github/workflows/        CI smoke and npm publish workflows
  assets/brand/             1AM Explorer-derived brand kit
  assets/project-overlay/   1AM project guidance copied into scaffolds
  assets/skills/            1AM Midnight and design skills
  assets/templates/         Bundled starter and contract templates
  assets/wallet/            Wallet integration docs and helper
  docs/                     Additional guides and E2E notes
  scripts/                  Local smoke test scripts
  src/                      TypeScript CLI source

Local Development

Install dependencies:

npm install

Run in development:

npm run dev -- --help

Build:

npm run build

Run the built CLI:

node dist/index.js --help

Test the global install behavior without touching your real global npm prefix:

npm run smoke:global

Link locally:

npm link
1am --help

Environment Variables

Common variables used by generated projects and deploy flows:

MIDNIGHT_SEED=<64-character-hex-seed>

You can also pass seeds or mnemonics directly with CLI flags, but environment variables are safer for repeatable local workflows.

Security Notes

• Do not commit seeds, mnemonics, API keys, .env files, or generated private state databases.
• The root .gitignore excludes .env, .tmp, .1am, local packed tarballs, node_modules, generated dist, and local audit databases.
• Preview/preprod deploy testing can use disposable seeds because ProofStation balances the deploy transaction.
• Treat mainnet deploys as irreversible production actions.

Design Principles

1AM CLI is built around a few practical rules:

• Make the first command obvious.
• Keep generated apps compact.
• Prefer official Midnight patterns where possible.
• Add 1AM conventions as overlays instead of hiding the underlying template.
• Make AI agents more useful by giving them local, repo-specific instructions.
• Keep deploy flows explicit about seed, network, proof server, indexer, and RPC.
• Keep the visual system aligned with the live 1AM Explorer.

Documentation

• Getting Started
• Brand And Design Guide
• Template Guide
• Publishing And Release Notes
• End-To-End Crowd Flow
• Agent Wallet Guide
• 1AM CLI Design Plan

Contribution

Contributions are welcome.

Good first areas:

• Add more starter templates.
• Expand official Midnight template coverage.
• Add more automated scaffold smoke tests.
• Improve deploy error messages.
• Add richer Explorer query helpers.
• Improve 1AM design assets and examples.
• Add more AI skills for Midnight app categories.

Before opening a pull request:

npm run verify
npm run smoke:global
npm pack --dry-run

Credits

• Product: 1AM
• Venture and engineering group: Webisoft
• Built by: Utkarsh Varma
• npm author metadata: UVROXX <[email protected]>
• Midnight developer ecosystem: Midnight Network

License

MIT.