Atlas Setup Command

This command guides users through configuring Atlas for first-time use.

Usage

/atlas setup

Wizard Flow

When this command is invoked, follow these steps interactively:

Step 1: Welcome

Display a welcome message explaining what Atlas does and what will be configured.

Step 2: GitHub Organization

Ask the user for their GitHub organization name. Validate that:

• The user has access to the organization (using gh api orgs/{org})
• The organization exists

Step 3: Knowledge Repository

Ask if the user has an existing knowledge repository or wants to create a new one:

• Existing: Ask for the path to the local clone
• New: Offer to create a new repository in their organization

Step 4: Product Repositories

Ask for paths to product repositories to connect. Allow multiple entries. Validate that each path exists and is a git repository.

Step 5: Vector Database (Optional)

Ask if the user wants to configure a vector database for semantic search:

• If yes, collect the PostgreSQL connection URL
• Recommend using an environment variable for security

Step 5.5: Initialize Database (if URL provided)

If the user provided a database URL, test and initialize it:

1. Test the connection:

DB_URL="${ATLAS_DATABASE_URL:-$USER_PROVIDED_URL}"
if psql "$DB_URL" -c "SELECT 1" &>/dev/null; then
    echo "Database connection: OK"
else
    echo "Database connection: FAILED"
    echo "Please check your connection URL and try again."
    # Offer to continue without database or re-enter URL
fi

2. Check for pgvector extension:

if psql "$DB_URL" -t -c "SELECT 1 FROM pg_extension WHERE extname = 'vector'" | grep -q 1; then
    echo "pgvector extension: INSTALLED"
else
    echo "pgvector extension: NOT FOUND"
    echo "Attempting to create extension..."
    psql "$DB_URL" -c "CREATE EXTENSION IF NOT EXISTS vector"
fi

3. Check if table exists:

if psql "$DB_URL" -c "SELECT 1 FROM atlas_embeddings LIMIT 1" &>/dev/null; then
    echo "Database table: EXISTS"
    # Show current stats
    psql "$DB_URL" -c "SELECT * FROM atlas_embedding_stats"
else
    echo "Database table: NOT FOUND"
fi

4. Offer to run migration if table missing:

Use AskUserQuestion:

The atlas_embeddings table doesn't exist yet. Would you like to create it now?

Options:
- Yes, create the table (Recommended)
- No, I'll do it later

5. If user agrees, run migration:

ATLAS_PLUGIN_DIR="path/to/plugins/atlas"
"$ATLAS_PLUGIN_DIR/scripts/db/migrate.sh"

6. Verify and report:

if psql "$DB_URL" -c "SELECT 1 FROM atlas_embeddings LIMIT 1" &>/dev/null; then
    echo "Database initialized successfully!"
    echo "You can now index knowledge with: /atlas update-knowledge <path>"
else
    echo "Migration may have failed. Check the output above."
    echo "You can run it manually later: ./plugins/atlas/scripts/db/migrate.sh"
fi

Step 6: Write Configuration

Create the ~/.atlas/config.yaml file with the collected information. Use environment variable placeholders for sensitive values.

Step 7: Verification

• Display the created configuration
• Verify GitHub access works
• Confirm setup is complete

Step 8: Next Steps

After successful setup, display helpful next steps:

Atlas Setup Complete!
=====================

Configuration saved to: ~/.atlas/config.yaml

Next Steps:
-----------

1. Add knowledge to your repository:
   /atlas update-knowledge ~/path/to/document.md

2. Search your knowledge base:
   /atlas search "your query"

3. Plan work from a goal:
   /atlas plan "Add user authentication"

4. Check configuration anytime:
   /atlas check-setup

Need help? Run /atlas help

If database was not configured:

Note: Semantic search is not enabled.
To enable it later:
1. Set ATLAS_DATABASE_URL environment variable
2. Run: ./plugins/atlas/scripts/db/migrate.sh
3. Index your knowledge: /atlas update-knowledge <path>

Implementation

Use the AskUserQuestion tool to gather information at each step. Use the Bash tool to:

• Validate GitHub access: gh api orgs/{org}
• Check if paths exist: test -d "{path}"
• Check if directories are git repos: git -C "{path}" rev-parse --git-dir
• Create config directory: mkdir -p ~/.atlas

Use the Write tool to create the configuration file.

Example Configuration Output

# Atlas Configuration
# Generated by /atlas setup

knowledge_repo: ~/repos/company-knowledge

product_repos:
  - ~/repos/main-app
  - ~/repos/api-service

github_org: acme-corp

vector_db:
  url: ${ATLAS_DATABASE_URL}
  table: atlas_embeddings
  dimensions: 1536

Re-running Setup

If ~/.atlas/config.yaml already exists:

1. Inform the user that configuration already exists
2. Ask if they want to modify it or start fresh
3. If modifying, show current values as defaults