Merge pull request #2 from pinecone-io/env-troubleshooting

Changes to correct env usage and fix index creation

Author: arjunpatel7

.agents/PINECONE-cli.md

@@ -48,6 +48,37 @@ pc auth login
 - **Use Option 2 (API Key)** or **Option 3 (Service Account)** instead
 - These methods work in all environments and are better suited for automation
 
+### Option 2a: Environment Variable (Recommended for Quickstarts)
+
+Simplest method - CLI reads `PINECONE_API_KEY` from your environment:
+
+1. Create `.env` file:
+
+```bash
+PINECONE_API_KEY=your-api-key-here
+```
+
+2. Load into shell:
+
+```bash
+source .env
+```
+
+3. Export for CLI use (required for quickstart):
+
+```bash
+export PINECONE_API_KEY
+```
+
+4. CLI commands now work automatically.
+
+**Benefits:**
+- Same API key for CLI and SDK
+- No separate configuration step
+- Perfect for development and quickstarts
+
+**Note:** Only persists for current shell session. For persistent auth, use Option 2 below.
+
 ### Option 2: API Key
 
 Use for most automated scenarios, CI/CD, or when browser access is unavailable. Scoped to a specific project.
@@ -135,10 +166,16 @@ pc api-key delete --key-id <key-id>
 # 1. Install CLI (check first: pc version)
 brew tap pinecone-io/tap && brew install pinecone-io/tap/pinecone
 
-# 2. Check authentication status (check first: pc auth status)
-# For interactive environments with browser access:
+# 2. Authenticate (choose one method):
+
+# Option A: Environment variable (recommended for quickstarts)
+# Create .env file with PINECONE_API_KEY=your-key, then:
+source .env
+
+# Option B: Interactive login (requires browser)
 pc auth login
-# OR for non-interactive/automated environments:
+
+# Option C: Direct API key configuration (persists across sessions)
 pc auth configure --api-key your-api-key
 
 # 3. Verify target (if already authenticated) and set it if needed
@@ -198,7 +235,7 @@ pc index create -n my-app-prod -m cosine -c aws -r us-east-1 \
 | ----------------------------------------- | -------------------------------------------------------------------------------- |
 | `pc: command not found`                   | Install CLI: `brew tap pinecone-io/tap && brew install pinecone-io/tap/pinecone` |
 | `Unknown command` or unrecognized command | See troubleshooting steps above (check version, update if needed)                |
-| `Authentication failed`                   | Run `pc auth login` or set an API key or service account                         |
+| `Authentication failed`                   | Run `source .env` (if using .env file), `pc auth login`, or `pc auth configure --api-key` |
 | `Index already exists`                    | Use different name or delete existing: `pc index delete --name <name>`           |
 | `Permission denied`                       | Check API key permissions or organization access                                 |
 

.agents/PINECONE-python.md

@@ -211,10 +211,26 @@ class PineconeClient:
 
 Complete setup prerequisites first, then:
 
+**Before running commands, ensure environment is ready:**
+
+```bash
+# Load API key into environment (CLI will use this)
+source .env
+
+# Export for CLI use (required for quickstart)
+export PINECONE_API_KEY
+
+# Activate virtual environment
+source venv/bin/activate
+```
+
 1. **Create index with CLI:**
 
 ```bash
 pc index create -n agentic-quickstart-test -m cosine -c aws -r us-east-1 --model llama-text-embed-v2 --field_map text=content
+
+# Wait for index to be ready
+sleep 5
 ```
 
 2. **Upsert sample data:**

.agents/PINECONE-quickstart.md

@@ -178,13 +178,37 @@ implementation 'io.pinecone:pinecone-client:5.1.0'
 
 **⚠️ Use `.env` files (see [PINECONE.md](./PINECONE.md#-environment-variables--security-best-practices) for details).**
 
-Create `.env` file:
+**Recommended Workflow (CLI + SDK):**
+
+1. **Create `.env` file** in your project root:
 
 ```bash
 PINECONE_API_KEY=your-api-key-here
 ```
 
-**CLI authentication:**
+2. **Load into your shell:**
+
+```bash
+source .env
+```
+
+3. **Export for CLI use** (required for quickstart):
+
+```bash
+export PINECONE_API_KEY
+```
+
+4. **Activate virtual environment** (if using Python):
+
+```bash
+source venv/bin/activate
+```
+
+Now both CLI commands (`pc index create ...`) and Python scripts (using `python-dotenv`) will use the same API key.
+
+**Alternative: Persistent CLI Authentication**
+
+If you prefer CLI authentication that persists across shell sessions:
 
 ```bash
 pc auth configure --api-key your-api-key-here
@@ -207,10 +231,11 @@ Add to `.env`: `OPENAI_API_KEY=...`, `ANTHROPIC_API_KEY=...`, or `GROQ_API_KEY=.
 ### Steps
 
 1. **Create an index** with integrated embeddings using CLI
-2. **Prepare sample data** from different domains (history, science, art, etc.)
-3. **Upsert data** into the index
-4. **Search** for semantically similar documents
-5. **Rerank results** for better accuracy
+2. **Wait for index** to be ready (sleep 5 seconds)
+3. **Prepare sample data** from different domains (history, science, art, etc.)
+4. **Upsert data** into the index
+5. **Search** for semantically similar documents
+6. **Rerank results** for better accuracy
 
 ### Sample Data (Use in All Languages)
 

.agents/PINECONE.md

@@ -71,7 +71,11 @@ Based on what the user is asking, consult these guides:
 
 ### ⚠️ Critical: CLI Authentication (When Using CLI)
 
-> **When using CLI for index creation or management**: ALWAYS check if the CLI is already authenticated by running `pc auth status` before prompting for authentication setup. See [PINECONE-cli.md](./PINECONE-cli.md#authentication) for details on interpreting the output.
+> **When using CLI for index creation or management**:
+>
+> **For quickstarts:** Create a `.env` file with `PINECONE_API_KEY` and run `source .env`. The CLI automatically detects the environment variable - no separate authentication needed.
+>
+> **For persistent authentication:** Run `pc auth status` to check if already authenticated. See [PINECONE-cli.md](./PINECONE-cli.md#authentication) for `pc auth configure` and other options.
 
 ### ⚠️ MANDATORY: Always Use Latest Version