Skip to content

README.md

Latest commit

 

History

History
224 lines (165 loc) · 10.7 KB

README.md

File metadata and controls

224 lines (165 loc) · 10.7 KB

Atmosphere CLI

Run samples, scaffold projects, and explore the Atmosphere framework from your terminal.

Quick Install

curl -fsSL https://raw.githubusercontent.com/Atmosphere/atmosphere/main/cli/install.sh | sh

Or with Homebrew:

brew install Atmosphere/tap/atmosphere

Usage

Interactive Install (recommended)

atmosphere install              # Browse all samples, pick one
atmosphere install --tag ai     # Filter to AI samples
atmosphere install --category tools

The interactive picker shows samples grouped by category with descriptions. Pick a number, then choose to:

  1. Run it now — downloads the pre-built JAR and starts it
  2. Install source code — clones the sample source into your current directory

If fzf is installed, you get a fuzzy-search picker instead of the numbered menu.

List Samples

atmosphere list                # All samples
atmosphere list --tag ai       # AI samples only
atmosphere list --category tools

Run a Sample

atmosphere run spring-boot-chat
atmosphere run spring-boot-ai-chat --env LLM_API_KEY=your-key
atmosphere run spring-boot-dentist-agent --port 9090

The CLI downloads pre-built JARs from GitHub Releases and caches them in ~/.atmosphere/cache/.

Create a New Project

atmosphere new my-chat-app
atmosphere new my-ai-app --template ai-chat
atmosphere new my-fleet --template multi-agent
atmosphere new my-classroom --template classroom

# Swap the AI runtime by injecting the matching adapter dependency
atmosphere new my-ai-app --template ai-chat --runtime langchain4j
atmosphere new my-ai-app --template ai-chat --runtime spring-ai
atmosphere new my-ai-app --template ai-chat --runtime adk
atmosphere new my-kotlin-ai --template ai-chat --runtime embabel

# Force-swap: strip every pre-pinned adapter before injecting the chosen one
atmosphere new my-ai-app --template ai-tools --runtime spring-ai --force

Available templates: chat, ai-chat, ai-tools, mcp-server, rag, agent, koog, embabel, multi-agent, classroom. Each template sparse-clones the matching sample from cli/samples.json into a directory you name.

Available runtimes (--runtime): builtin (default — no extra deps), spring-ai, langchain4j, adk, koog, semantic-kernel, agentscope, embabel, spring-ai-alibaba. The CLI appends the matching adapter dependencies (and any required repository, such as Embabel's release repository) to the scaffolded pom.xml — Atmosphere's AgentRuntime SPI then picks the highest-priority runtime present, so transparent templates like ai-chat swap runtime adapters without code changes. embabel and spring-ai-alibaba currently target the Spring Boot 3.5 profile.

--force (only valid with --runtime) wipes every adapter dep declared in cli/runtime-overlays.json from the scaffolded pom.xml before injecting the chosen overlay. This makes the swap deterministic on samples that already pin a non-default adapter (e.g. ai-tools ships with atmosphere-langchain4j) — without --force, both adapters would land on the classpath and the SPI resolver would pick one based on ServiceLoader iteration order. Note: samples whose Java code imports a specific provider's API directly (e.g. OpenAiStreamingChatModel) will still need manual edits after force-swap; transparent templates (ai-chat, multi-agent) work end-to-end with no code changes.

10-minute enterprise agent path

Use this path when the goal is a production-shaped JVM agent rather than a minimal chat demo:

atmosphere new support-agent --template ai-tools --runtime builtin
cd support-agent
export LLM_API_KEY=...
mvn spring-boot:run

The Spring Boot starter already brings in atmosphere-admin, so the generated app has the dashboard, /api/admin/runtimes, audit log, A2A flow viewer, and governance decision endpoints on the classpath. Then harden the control plane:

  1. Turn on mutating admin operations only behind auth: atmosphere.admin.http-write-enabled=true plus a ControlAuthorizer.
  2. Move proprietary documents into the rag template when retrieval is needed; it chunks documents with RagChunker before embedding them.
  3. Pick the runtime by capability, not by brand. For portable tools and HITL, use a runtime that declares TOOL_CALLING and TOOL_APPROVAL in modules/ai/README.md.

Or with npx (zero install):

npx create-atmosphere-app my-chat-app
npx create-atmosphere-app my-ai-app --template ai-chat

Sample Info

atmosphere info spring-boot-ai-chat

Import a Skill from GitHub

Turn any skill file into a running Atmosphere agent:

# From Anthropic's official skills
atmosphere import https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

# From Antigravity community (1,200+ skills)
atmosphere import https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills/customer-support/SKILL.md

# From a local file
atmosphere import ./my-skill.md

# Custom project name
atmosphere import --name my-agent https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md

# Headless agent (A2A/MCP only, no WebSocket UI)
atmosphere import --headless https://example.com/SKILL.md --trust

The import command:

  • Downloads the skill file (GitHub blob URLs auto-normalized to raw)
  • Parses YAML frontmatter for name: and description:
  • Extracts ## Tools sections → generates @AiTool method stubs
  • Scaffolds a complete Spring Boot project
  • Places the skill at META-INF/skills/{name}/SKILL.md for auto-discovery

Skills Registry

Browse and run curated skills from atmosphere-skills:

atmosphere skills list                # List all skills
atmosphere skills search medical      # Search by keyword
atmosphere skills run dentist-agent   # Scaffold and run

Trusted Sources

Remote imports are restricted to trusted GitHub organizations by default:

Trusted Source Repository
Atmosphere/* atmosphere-skills
anthropics/skills Official Anthropic skills
sickn33/antigravity-awesome-skills 1,200+ community skills
K-Dense-AI/* Scientific/research skills
agentskills/* Agent Skills spec

To import from an untrusted source, use --trust:

atmosphere import --trust https://example.com/custom/SKILL.md

Import Plugins

The import command supports plugins for custom project scaffolding targets. Plugins are shell scripts at ~/.atmosphere/plugins/import-<target>.sh:

atmosphere import --target kotlin https://example.com/SKILL.md   # uses import-kotlin.sh
atmosphere plugins                                                # list installed plugins

Available Templates

Every template sparse-clones the matching sample from cli/samples.json into the directory you name, then rewrites the cloned pom.xml so its parent (org.atmosphere:atmosphere-project) resolves from Maven Central instead of the reactor root — the resulting project compiles standalone with mvn compile / mvn spring-boot:run.

Template Source sample Description
chat (default) spring-boot-chat Real-time WebSocket chat with rooms, observability, integration tests
ai-chat spring-boot-ai-chat AI streaming chat (Spring AI / LangChain4j / Gemini / Ollama) with structured-output demo
ai-tools ⭐ spring-boot-ai-tools Enterprise starter: @AiTool function calling, HITL approval, cost metering, audit listener
mcp-server spring-boot-mcp-server MCP server exposing tools, resources, and prompts to AI agents
rag ⭐ spring-boot-rag-chat RAG agent with chunked vector-store ingestion and explicit document-search tools
agent spring-boot-dentist-agent @Agent skill-file driven (the Dr. Molar demo); implied when --skill-file is passed
coding-agent ⭐ spring-boot-coding-agent Sandbox SPI + Git clone + AgentResumeHandle reattach; reads files and proposes patches
guarded-agent ⭐ spring-boot-guarded-email-agent Plan-and-Verify (Meijer) — refuses unsafe LLM-emitted plans before any tool fires
ms-governance ⭐ spring-boot-ms-governance-chat Governance demo: policy admission, decision viewer, kill switch, write-gated admin endpoints
assistant spring-boot-personal-assistant Long-lived memory-bearing assistant: AgentState + AgentWorkspace + AgentIdentity + ProtocolBridge
multi-agent spring-boot-multi-agent-startup-team Fleet of 5 independent @Agent classes collaborating over A2A
classroom spring-boot-ai-classroom Shared streaming AI responses across web + Expo React Native clients

⭐ marks the five flagship enterprise templates — the canonical agent shapes most teams reach for first. Each one is a real sample with a working backend, a working frontend, and end-to-end tests; pick the one whose use case is closest to yours and substitute model/data accordingly. See samples/README.md#flagship-enterprise-templates for the full breakdown.

Requirements

  • Java 21+ — brew install openjdk@21 or SDKMAN
  • Maven 3.9+ — automatically on PATH via Homebrew/SDKMAN, or use the mvnw wrapper shipped with samples
  • Git — for the sparse-checkout used by atmosphere new and atmosphere install
  • JBang — only needed for atmosphere compose (skill-file driven multi-agent scaffolding); not required for atmosphere new

Architecture

cli/
├── atmosphere          # POSIX shell CLI script
├── samples.json        # Sample registry with metadata
├── install.sh          # curl | sh installer
├── npx/                # create-atmosphere-app npm package
│   ├── package.json
│   └── index.js
└── homebrew/
    └── atmosphere.rb   # Homebrew formula (for Atmosphere/homebrew-tap)

atmosphere run downloads sample fat JARs from GitHub Releases on first use and caches them in ~/.atmosphere/cache/v{version}/. atmosphere new and atmosphere install use git sparse-checkout to fetch just the requested sample directory from Atmosphere/atmosphere@main. The release workflow (.github/workflows/release-4x.yml) stamps pinned versions across cli/atmosphere, cli/samples.json, cli/npx/package.json, and cli/homebrew/atmosphere.rb via scripts/update-doc-versions.sh before publishing a GitHub Release.