Atlas CLI

Knowledge base: platform & integrations

Navigate Atlas modules (orchestrator, memory, tools, API) and connect external services using OAuth— Gmail and Microsoft 365 are supported out of the box with token files under .atlas/.

Overview

Atlas CLI is a Typer application whose default is interactive multi-turn chat. The orchestrator coordinates the LLM, tools, memory, and optional domain RAG. Use this KB to see where features live and how to wire OAuth for cloud mail and calendars.

Tip: Run from the project root so .env and .atlas/ paths resolve. You can use launch_AtlasCli.py at the repo root to set the working directory automatically.

Entry points

Surface How to run Role
Primary CLI python3 atlas_cli.py or python3 main.py Chat, run, about; sub-apps: memory, manage, domain, llm, connect, gmail, o365, background jobs (bg), and more.
HTTP API uvicorn api.server:app --reload --port 8000 FastAPI control plane for agent runs, scheduling, automation triggers (e.g. n8n), optional token protection via ATLAS_AUTOMATION_API_TOKEN.
Launcher python3 launch_AtlasCli.py Same CLI; ensures cwd is the Atlas project root.

Module map (where to look)

Package Responsibility
agent/ Orchestration (orchestrator.py), intent, planning (optional LangGraph: planner_graph.py, atlas_coding_graph.py), tools execution, review, reflection, self-healing hooks, task store.
services/ Audit logging, budget tracking, MCP registry, background jobs, automation clients (n8n/UiPath).
memory/ Chroma vector store, episodic/personal memory, Atlas docs indexing.
tools/ Filesystem, shell, web, feeds, open data—invoked through the execution layer.
domain_rag/ Domain-tagged corpora (legal, finance, tax, etc.) for retrieval-augmented answers.
integrations/ OAuth helpers and API clients—used when tools or CLIs call Gmail, Microsoft Graph, web search, etc.
models/ LLM router: Ollama, Azure OpenAI, OpenAI, Anthropic.
api/ FastAPI app for remote and automation-driven runs.

How a request flows (simplified)

  1. Input arrives via CLI or API → orchestrator.
  2. Intent and memory retrieval shape the prompt; optional domain RAG adds context.
  3. The LLM proposes tools; execution runs allowed actions (files, integrations, MCP).
  4. Observer/reviewer and optional reflection refine the outcome; audit events go to logs/.

For the full turn-by-turn narrative, see atlas_framework_technical_flow.md in the repo docs/ folder.

OAuth & external services

Atlas connects to third-party APIs using OAuth 2.0 where providers require it. You register an app in Google Cloud or Microsoft Entra (Azure AD), download client credentials, set environment variables, then run a connect flow once; tokens are stored under .atlas/ for reuse.

General checklist

  • Keep client secrets out of version control; use .env (not committed).
  • Use absolute paths for secret JSON when required by env vars.
  • Restrict OAuth scopes to the minimum (read-only mail vs send, etc.).
  • Rotate tokens if a workstation is lost; delete token files and reconnect.

Gmail (Google)

Required: ATLAS_GMAIL_CLIENT_SECRET pointing to your Google OAuth client JSON (e.g. client_secret.json from Google Cloud Console). Atlas can auto-detect a file under keys/*.json if the env var is unset.

Connect (browser/device flow)

python3 atlas_cli.py connect gmail
# or: bash scripts/connect-gmail.sh

Token file: .atlas/gmail_token.json

Useful commands:

python3 atlas_cli.py gmail status
python3 atlas_cli.py gmail list -n 20
python3 atlas_cli.py gmail show <message_id>

Microsoft 365 (Graph)

Required: ATLAS_O365_CLIENT_ID for your app registration. Optional: ATLAS_O365_TENANT_ID (often common for multi-tenant), ATLAS_O365_SCOPE for delegated permissions (mail, calendar, tasks).

Connect

python3 atlas_cli.py connect o365
# or: bash scripts/connect-o365.sh

Token file: .atlas/o365_token.json

Examples: o365 status, o365 mail-list, o365 mail-send, calendar and task subcommands—see atlas_cli.py o365 --help.

API, n8n, and signing

Run the FastAPI server for remote triggers. Protect automation routes with ATLAS_AUTOMATION_API_TOKEN. For n8n webhooks, configure ATLAS_N8N_SIGNING_SECRET for HMAC validation where supported. Outbound n8n/UiPath URLs and tokens are set via env (see integrations doc). 

uvicorn api.server:app --reload --port 8000

Repository documentation

These files ship with the Atlas CLI repo (not this static site):

  • docs/PLATFORM_MODULES.md — full module catalog and cross-links.
  • docs/INTEGRATIONS_SETUP.md — LLM providers, Gmail, O365, API security, MCP profiles.
  • docs/atlas_framework_technical_flow.md — runtime sequence.

Home · Contact