Update `README.md` and `CONTRIBUTING.md` by austin-denoble · Pull Request #46 · pinecone-io/cli

austin-denoble · 2025-10-09T05:46:54Z

Problem

We need to update the README.md and CONTRIBUTING.md files for the upcoming public preview release.

Solution

Update both. I've cribbed a lot from @bradumbaugh's docs changes, and tried to keep things somewhat brief and link externally.

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update
Infrastructure change (CI configs, etc)
Non-code change (docs, etc)
None of the above: (explain here)

Test Plan

N/A - view markdown

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1211584046063919

claude · 2025-10-09T05:47:07Z

Claude finished @austin-denoble's task —— View job

PR Review: Update README.md and CONTRIBUTING.md

Reviewing this PR for code quality, potential issues, performance, security, and test coverage.

Progress:

Read repository guidelines (CLAUDE.md)
Review CONTRIBUTING.md changes
Review README.md changes
Review Go code change (configure.go)
Provide comprehensive feedback and recommendations

Review Summary

This is a well-executed documentation update that significantly improves the user experience for the public preview release. The changes are appropriate, comprehensive, and well-structured.

✅ Strengths

README.md improvements:

Excellent restructuring from alpha to public preview messaging
Comprehensive installation section with multiple methods (Homebrew, direct download, source)
Clear authentication documentation with comparison table showing method capabilities
Step-by-step installation instructions with verification steps
Proper cross-platform support documentation
Links to external documentation for more details

CONTRIBUTING.md improvements:

Added just tool installation step for better developer experience
Improved code block formatting (shell → bash)
Minor formatting consistency improvements (added periods to bullet points)
Better structured build instructions

Code change:

Simple but important HTTP → HTTPS URL fix in configure.go:50

🔍 Observations

No significant issues found:

All changes are documentation/formatting improvements
No security concerns
No performance implications
No breaking changes
Test coverage not applicable for documentation changes

💡 Minor Suggestions

README.md line 5: Consider making the public preview link more specific if there's a dedicated CLI preview page rather than the general feature availability page.
Consistency: The README uses both "Pinecone CLI" and "CLI" - this is fine but worth noting for future consistency.
CONTRIBUTING.md: The "justfile" link points to the main branch - consider if this should be relative or if the current approach is intentional.

📋 Quality Assessment

Documentation Quality: Excellent - clear, comprehensive, well-organized
User Experience: Significantly improved with step-by-step instructions
Formatting: Consistent and professional
Information Architecture: Well-structured with logical flow
External Links: Appropriate use of links to official documentation

✅ Recommendation

Approve - This PR successfully prepares the documentation for public preview with comprehensive improvements that will greatly benefit users. The changes are well-thought-out and execution is solid.

claude · 2025-10-09T06:06:20Z

Claude finished @austin-denoble's task —— View job

PR Review: Update README.md and CONTRIBUTING.md

Reviewing this PR for code quality, potential issues, performance, security, and test coverage.

Progress:

Read repository guidelines (CLAUDE.md)
Review CONTRIBUTING.md changes
Review README.md changes
Review Go code change (configure.go)
Provide comprehensive feedback and recommendations

Review Summary

This is a well-executed documentation update that significantly improves the user experience for the public preview release. The changes are appropriate, comprehensive, and well-structured.

✅ Strengths

README.md improvements:

Excellent restructuring from alpha to public preview messaging
Comprehensive installation section with multiple methods (Homebrew, direct download, source)
Clear authentication documentation with comparison table showing method capabilities
Step-by-step installation instructions with verification steps
Proper cross-platform support documentation
Links to external documentation for more details

CONTRIBUTING.md improvements:

Added just tool installation step for better developer experience
Improved code block formatting (shell → bash)
Minor formatting consistency improvements (added periods to bullet points)
Better structured build instructions

Code change:

Simple but important HTTP → HTTPS URL fix in configure.go:50

🔍 Observations

No significant issues found:

All changes are documentation/formatting improvements
No security concerns
No performance implications
No breaking changes
Test coverage not applicable for documentation changes

💡 Minor Suggestions

README.md line 5: Consider making the public preview link more specific if there's a dedicated CLI preview page rather than the general feature availability page.
Consistency: The README uses both "Pinecone CLI" and "CLI" - this is fine but worth noting for future consistency.
CONTRIBUTING.md: The "justfile" link points to the main branch - consider if this should be relative or if the current approach is intentional.

📋 Quality Assessment

Documentation Quality: Excellent - clear, comprehensive, well-organized
User Experience: Significantly improved with step-by-step instructions
Formatting: Consistent and professional
Information Architecture: Well-structured with logical flow
External Links: Appropriate use of links to official documentation

✅ Recommendation

Approve - This PR successfully prepares the documentation for public preview with comprehensive improvements that will greatly benefit users. The changes are well-thought-out and execution is solid.

bradumbaugh

@austin-denoble Looks good, just a few minor things.

bradumbaugh · 2025-10-09T06:20:05Z

README.md

+If you don't have Homebrew installed, install it first:

-The most convenient way to install this is via [Homebrew](https://brew.sh)
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```


@austin-denoble Maybe just link to their installation instructions, in case they change?

We link to the brew landing page above, and this command is basically their recommended form of installation:

bradumbaugh · 2025-10-09T06:21:42Z

README.md

+- macOS (x86_64, ARM64)
+- Linux (x86_64, ARM64)
+- Windows (x86_64)


In the docs, I have:

macOS: Intel (x86_64) and Apple Silicon (ARM64)
Linux: x86_64, ARM64, and i386 architectures
Windows: x86_64 and i386 architectures

bradumbaugh · 2025-10-09T06:22:15Z

README.md

+- Control plane–related commands (index management):
+  - `pc index` (`create`, `list`, `describe`, `configure`, `delete`)
+
+### 1. User Login (Recommended for Interactive Use)


Suggested change

### 1. User Login (Recommended for Interactive Use)

### 1. User Login (Recommended for interactive use)

bradumbaugh · 2025-10-09T06:22:45Z

README.md

-pc index create-serverless --name example-index --dimension 1536 --metric cosine --cloud aws --region us-west-2
-pc index create-serverless --name="example-index" --dimension=1536 --metric="cosine" --cloud="aws" --region="us-west-2"
-pc index create-serverless -n example-index -d 1536 -m cosine -c aws -r us-west-2
+### 2. Service Account Authentication


Suggested change

### 2. Service Account Authentication

### 2. Service account authentication

bradumbaugh · 2025-10-09T06:23:14Z

README.md

+pc auth configure --client-id "client-id" --client-secret "client-secret" --project-id "project-id"
+```
+
+### 3. API Key Authentication


Suggested change

### 3. API Key Authentication

### 3. API key authentication

bradumbaugh · 2025-10-09T06:24:04Z

README.md

+pc config set-api-key "YOUR_API_KEY"
+```
+
+For more detailed information, see the [CLI Authentication documentation](https://docs.pinecone.io/reference/cli/authentication).


Suggested change

For more detailed information, see the [CLI Authentication documentation](https://docs.pinecone.io/reference/cli/authentication).

For more detailed information, see the [CLI authentication](https://docs.pinecone.io/reference/cli/authentication) documentation.

bradumbaugh · 2025-10-09T06:24:11Z

README.md

+
+For more detailed information, see the [CLI Authentication documentation](https://docs.pinecone.io/reference/cli/authentication).
+
+## Quick Start


Suggested change

## Quick Start

## Quickstart

bradumbaugh · 2025-10-09T06:25:13Z

README.md

+
+## Quick Start
+
+After installation, get started with authentication:


Suggested change

After installation, get started with authentication:

After installing the CLI, authenticate with user login or set an API key, verify your auth status, and list indexes associated with your automatically targeted project.

bradumbaugh · 2025-10-09T06:25:51Z

README.md


-# Additionally, you can authenticate through the browser using the login command
-pc login
+The standard authentication method for interactive use. Provides full access to the Admin API and control/data plane operations. You will have access to all organizations associated with the account.


Suggested change

The standard authentication method for interactive use. Provides full access to the Admin API and control/data plane operations. You will have access to all organizations associated with the account.

The standard authentication method for interactive use. Provides full access to the Admin API and control/data plane operations. When authenticated this way, you have access to all organizations associated with the account.

bradumbaugh · 2025-10-09T06:26:08Z

README.md

-pc index list
-pc index list --json
+```bash
+# Will prompt you to pick a target project from the projects available to the service account


Suggested change

# Will prompt you to pick a target project from the projects available to the service account

# Prompts you to pick a target project from the projects available to the service account

claude · 2025-10-09T07:43:13Z

Claude finished @austin-denoble's task —— View job

PR Review: Update README.md and CONTRIBUTING.md

Reviewing this PR for code quality, potential issues, performance, security, and test coverage.

Progress:

Read repository guidelines (CLAUDE.md)
Review CONTRIBUTING.md changes
Review README.md changes
Review Go code change (configure.go)
Provide comprehensive feedback and recommendations

Review Summary

This is a well-executed documentation update that significantly improves the user experience for the public preview release. The changes are appropriate, comprehensive, and well-structured.

✅ Strengths

README.md improvements:

Excellent restructuring from alpha to public preview messaging
Comprehensive installation section with multiple methods (Homebrew, direct download, source)
Clear authentication documentation with comparison table showing method capabilities
Step-by-step installation instructions with verification steps
Proper cross-platform support documentation
Links to external documentation for more details

CONTRIBUTING.md improvements:

Added just tool installation step for better developer experience
Improved code block formatting (shell → bash)
Minor formatting consistency improvements (added periods to bullet points)
Better structured build instructions

Code change:

Simple but important HTTP → HTTPS URL fix in configure.go:50

🔍 Observations

No significant issues found:

All changes are documentation/formatting improvements
No security concerns
No performance implications
No breaking changes
Test coverage not applicable for documentation changes

💡 Minor Suggestions

README.md line 5: Consider making the public preview link more specific if there's a dedicated CLI preview page rather than the general feature availability page.
Consistency: The README uses both "Pinecone CLI" and "CLI" - this is fine but worth noting for future consistency.
CONTRIBUTING.md: The "justfile" link points to the main branch - consider if this should be relative or if the current approach is intentional.

📋 Quality Assessment

Documentation Quality: Excellent - clear, comprehensive, well-organized
User Experience: Significantly improved with step-by-step instructions
Formatting: Consistent and professional
Information Architecture: Well-structured with logical flow
External Links: Appropriate use of links to official documentation

✅ Recommendation

Approve - This PR successfully prepares the documentation for public preview with comprehensive improvements that will greatly benefit users. The changes are well-thought-out and execution is solid.

claude · 2025-10-09T07:52:32Z

Claude finished @austin-denoble's task —— View job

PR Review: Update README.md and CONTRIBUTING.md

Reviewing this PR for code quality, potential issues, performance, security, and test coverage.

Progress:

Read repository guidelines (CLAUDE.md)
Review CONTRIBUTING.md changes
Review README.md changes
Review Go code change (configure.go)
Provide comprehensive feedback and recommendations

Review Summary

This is a well-executed documentation update that significantly improves the user experience for the public preview release. The changes are appropriate, comprehensive, and well-structured.

✅ Strengths

README.md improvements:

Excellent restructuring from alpha to public preview messaging
Comprehensive installation section with multiple methods (Homebrew, direct download, source)
Clear authentication documentation with comparison table showing method capabilities
Step-by-step installation instructions with verification steps
Proper cross-platform support documentation
Links to external documentation for more details

CONTRIBUTING.md improvements:

Added just tool installation step for better developer experience
Improved code block formatting (shell → bash)
Minor formatting consistency improvements (added periods to bullet points)
Better structured build instructions

Code change:

Simple but important HTTP → HTTPS URL fix in configure.go:50

🔍 Observations

No significant issues found:

All changes are documentation/formatting improvements
No security concerns
No performance implications
No breaking changes
Test coverage not applicable for documentation changes

💡 Minor Suggestions

README.md line 5: Consider making the public preview link more specific if there's a dedicated CLI preview page rather than the general feature availability page.
Consistency: The README uses both "Pinecone CLI" and "CLI" - this is fine but worth noting for future consistency.
CONTRIBUTING.md: The "justfile" link points to the main branch - consider if this should be relative or if the current approach is intentional.

📋 Quality Assessment

Documentation Quality: Excellent - clear, comprehensive, well-organized
User Experience: Significantly improved with step-by-step instructions
Formatting: Consistent and professional
Information Architecture: Well-structured with logical flow
External Links: Appropriate use of links to official documentation

✅ Recommendation

Approve - This PR successfully prepares the documentation for public preview with comprehensive improvements that will greatly benefit users. The changes are well-thought-out and execution is solid.

austin-denoble added 2 commits October 9, 2025 00:53

fix http->https in doc comment

5b140a8

update the README for public preview, update CONTRIBUTING

ecb32bf

austin-denoble requested review from bradumbaugh and jhamon October 9, 2025 05:46

tweak

3342bf8

bradumbaugh approved these changes Oct 9, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into adenoble/update-README

8d4896b

review feedback

c09cc26

austin-denoble merged commit 39a7b73 into main Oct 9, 2025
5 checks passed

austin-denoble deleted the adenoble/update-README branch October 9, 2025 07:59

	### 1. User Login (Recommended for Interactive Use)
	### 1. User Login (Recommended for interactive use)

	### 2. Service Account Authentication
	### 2. Service account authentication

	For more detailed information, see the [CLI Authentication documentation](https://docs.pinecone.io/reference/cli/authentication).
	For more detailed information, see the [CLI authentication](https://docs.pinecone.io/reference/cli/authentication) documentation.


		For more detailed information, see the [CLI Authentication documentation](https://docs.pinecone.io/reference/cli/authentication).

		## Quick Start


		## Quick Start

		After installation, get started with authentication:

	After installation, get started with authentication:
	After installing the CLI, authenticate with user login or set an API key, verify your auth status, and list indexes associated with your automatically targeted project.

	The standard authentication method for interactive use. Provides full access to the Admin API and control/data plane operations. You will have access to all organizations associated with the account.
	The standard authentication method for interactive use. Provides full access to the Admin API and control/data plane operations. When authenticated this way, you have access to all organizations associated with the account.

	# Will prompt you to pick a target project from the projects available to the service account
	# Prompts you to pick a target project from the projects available to the service account

Conversation

austin-denoble commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Type of Change

Test Plan

Uh oh!

claude bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Update README.md and CONTRIBUTING.md

Progress:

Review Summary

✅ Strengths

🔍 Observations

💡 Minor Suggestions

📋 Quality Assessment

✅ Recommendation

Uh oh!

claude bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Update README.md and CONTRIBUTING.md

Progress:

Review Summary

✅ Strengths

🔍 Observations

💡 Minor Suggestions

📋 Quality Assessment

✅ Recommendation

Uh oh!

bradumbaugh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claude bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Update README.md and CONTRIBUTING.md

Progress:

Review Summary

✅ Strengths

🔍 Observations

💡 Minor Suggestions

📋 Quality Assessment

✅ Recommendation

Uh oh!

claude bot commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Update README.md and CONTRIBUTING.md

Progress:

Review Summary

✅ Strengths

🔍 Observations

💡 Minor Suggestions

📋 Quality Assessment

✅ Recommendation

Uh oh!

Uh oh!

Reviewers

Assignees

austin-denoble commented Oct 9, 2025 •

edited

Loading

claude bot commented Oct 9, 2025 •

edited

Loading

claude bot commented Oct 9, 2025 •

edited

Loading

claude bot commented Oct 9, 2025 •

edited

Loading

claude bot commented Oct 9, 2025 •

edited

Loading