planetlabs · carl-adams-planet · Apr 9, 2025 · Apr 10, 2025 · Apr 11, 2025 · Apr 12, 2025
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
@@ -24,7 +24,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pip
 
-      - name: Build, verify, and upload to TestPyPI
+      - name: Build, verify, and upload to PyPI
         run: |
           pip install --upgrade nox
           nox -s build publish_pypi

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
diff --git a/.gitignore b/.gitignore
@@ -23,7 +23,9 @@ coverage.xml
 *.pyc
 
 # Editors
+.idea/
 .vscode/
 # Docs build
 site
 .venv
+venv
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,10 +19,12 @@ insofar as is practical within the scope of changes targeted to the next major r
 versioning, major releases do not guarantee backwards compatibility.  Stability is not guaranteed
 during the development cycle.
 
-During the development cycle of a new major release, `RELEASE-PLANNING-X.0.md` should be maintained
-with a brief summary of the major and breaking changes underpinning the reason for the upcoming
-major release version.  Upon release, this content is expected to be folded into package documentation
-as appropriate, and this file should be removed.
+During the development cycle of a new major release, a GitHub Project and Milestone should be
+created to track changes targeted the release.  A file such as `RELEASE-PLANNING-X.0.md` in the
+root of the source tree may be used for early development prior to the creation of a GitHub
+project, but should be retired when a new release becomes more formalized.  Upon release,
+all content is expected to be folded into package documentation as appropriate (announcements,
+company blog posts, changelogs, migration guides, etc.).
 
 When a new major release is ready, the development mainline branch will be renamed to `main`, and the
 old mainline branch will be renamed to `maint-X.0` and will be used as the base for maintenance releases.

diff --git a/README.md b/README.md
@@ -81,11 +81,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#branches) for more information on branches
 
 ##### Current Mainline Versions and Branches
 
-| Version | Status        | Branch                                                                                 | Documentation                                                                                                | Initial Release | End of Active Development | End of Maintenance | Notes                                                                                                                        |
-|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------|
-| 3.x     | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | TBD                                                                                                          | TBD             | TBD                       | TBD                | See [RELEASE-PLANNING-X.0.md](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev/RELEASE-PLANNING-3.0.md). |
-| 2.x     | `active`      | [`main`](https://github.com/planetlabs/planet-client-python/tree/main)                 | [Planet Labs Python Client v2 on Readthedocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023      | TBD                       | TBD                |                                                                                                                              |
-| 1.x     | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1)                     | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/)              | April 2017      | April 2023                | TBD                |                                                                                                                              |
+| Version | Status        | Branch                                                                                 | Documentation                                                                                                | Initial Release | End of Active Development | End of Maintenance | Notes                                                                                           |
+|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|-------------------------------------------------------------------------------------------------|
+| 3.x     | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | [Planet Labs Python Client on ReadTheDocs.io](https://planet-sdk-for-python.readthedocs.io/en/latest/)       | TBD             | TBD                       | TBD                | See [3.0.0 Release Milestone](https://github.com/planetlabs/planet-client-python/milestone/31). |
+| 2.x     | `active`      | [`main`](https://github.com/planetlabs/planet-client-python/tree/main)                 | [Planet Labs Python Client v2 on ReadTheDocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023      | TBD                       | TBD                |                                                                                                 |
+| 1.x     | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1)                     | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/)              | April 2017      | April 2023                | TBD                |                                                                                                 |
 
 ## Installation and Quick Start
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -54,7 +54,6 @@ The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and t
      * _`version`_: [https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/](https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/) - Should point to version `X.YY.ZZ`.
    * Pre-release versions should _not_ impact the default version of the documentation. Pre-release version may be published as the `latest` version.
 
-
 ## Local publishing
 
 Publishing to testpypi and pypi can also be performed locally with:

diff --git a/docs/cli/cli-guide.md b/docs/cli/cli-guide.md
@@ -34,13 +34,13 @@ Yes. Even if you’re not writing code—and only using the "no code" CLI part o
 Install the Planet SDK for Python using [pip](https://pip.pypa.io):
 
 ```console
-$ pip install planet
+pip install planet
 ```
 
 ## Step 3: Check the Planet SDK for Python version
 
 ```console
-$ planet --version
+planet --version
 ```
 
 You should be on some version 2 of the Planet SDK for Python.
@@ -55,46 +55,40 @@ To confirm your Planet account, or to get one if you don’t already have one, s
 
 ### Authenticate with the Planet server
 
-Just as you log in when you browse to https://account.planet.com, you’ll want to sign on to your account so you have access to your account and orders.
+Just as you log in when you browse to https://planet.com/account, you’ll want to sign on to your account so you have access to your account and orders.
 
 At a terminal console, type the following Planet command:
 
 ```console
-$ planet auth init
+planet auth login
 ```
 
-You’ll be prompted for the email and password you use to access [your account](https://account.planet.com). When you type in your password, you won’t see any indication that the characters are being accepted. But when you hit enter, you’ll know that you’ve succeeded because you’ll see on the command line:
+A browser window should be opened, and you will be directed to login to your account.  This
+command will wait for the browser login to complete, and should exit shortly afterwards.
+When this process succeeds, you will see the following message on the console:
 
 ```console
-Initialized
+Login succeeded.
 ```
 
-### Get your API key
-
-Now that you’ve logged in, you can easily retrieve your API key that is being used for requests with the following command:
-
+If you are in an environment where the `planet` command line utility cannot open a browser (such 
+as a remote shell on a cloud service provider), use the following command and follow the instructions:
 ```console
-planet auth value
+planet auth login --no-open-browser
 ```
 
-Many `planet` calls you make require an API key. This is a very convenient way to quickly grab your API key.
-
-#### Your API Key as an Environment Variable
+### Get your Access Token
 
-You can also set the value of your API Key as an environment variable in your terminal at the command line:
+Now that you’ve logged in, you can easily retrieve an Access Token that is being used for requests with the following command:
 
 ```console
-export PL_API_KEY=<your api key>
+planet auth print-access-token
 ```
 
-And you can see that the value was stored successfully as an environment variable with the following command:
-
-```console
-echo $PL_API_KEY
-```
+Many `planet` calls you make require an access token. This is a very convenient way to quickly grab the current access token.
 
-!!!note "The API Key environment variable is ignored by the CLI but used by the Python library"
-    If you do create a `PL_API_KEY` environment variable, the CLI will be unaffected but the Planet library will use this as the source for authorization instead of the value stored in `planet auth init`.
+**Note** : As a security measure, access tokens are time limited. They have a relatively short lifespan, and must
+be refreshed.  The `print-access-token` command takes care of this transparently for the user.
 
 ## Step 5: Search for Planet Imagery
 

diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md
@@ -4,8 +4,10 @@ title: CLI Reference
 
 This page provides documentation for our command line tools.
 
+{% raw %}
 ::: mkdocs-click
     :module: planet.cli.cli
     :command: main 
     :prog_name: planet
     :depth: 1
+{% endraw %}
diff --git a/docs/get-started/quick-start-guide.md b/docs/get-started/quick-start-guide.md
@@ -27,10 +27,12 @@ pip install planet
 
 ### Authentication
 
-Use the `PL_API_KEY` environment variable to authenticate with the Planet API. For other authentication options, see the [SDK guide](../python/sdk-guide.md).
+Use the `planet auth` CLI command to establish a user login session that will
+be saved to the user's home directory.  For other authentication options, see
+the [Client Authentication Guide](../python/sdk-client-auth.md).
 
 ```bash
-export PL_API_KEY=your_api_key
+planet auth login
 ```
 
 ### The Planet client
@@ -39,7 +41,7 @@ The `Planet` class is the main entry point for the Planet SDK. It provides acces
 
 ```python
 from planet import Planet
-pl = Planet()  # automatically detects PL_API_KEY
+pl = Planet()  # automatically detects authentication configured by `planet auth login`
 ```
 
 The Planet client has members `data`, `orders`, and `subscriptions`, which allow you to interact with the Data API, Orders API, and Subscriptions API. Usage examples for searching, ordering and creating subscriptions can be found in the [SDK guide](../python/sdk-guide.md).

diff --git a/docs/get-started/upgrading.md → docs/get-started/upgrading-v2.md b/docs/get-started/upgrading.md → docs/get-started/upgrading-v2.md
diff --git a/docs/get-started/upgrading-v3.md b/docs/get-started/upgrading-v3.md
@@ -0,0 +1,95 @@
+# Upgrade from Version 2 to Version 3
+
+Version 3 of the Planet SDK for Python is a major update of the SDK offering
+new features, not all of which are backwards compatible with version 2.
+
+## Authentication
+Version 3 of the SDK removes support for Planet's legacy authentication network
+protocols in favor of OAuth2 based mechanisms.  The legacy protocols
+were never a [documented Planet API](https://docs.planet.com/develop/apis/), but could
+easily be understood by inspection of the SDK code.
+
+Specifically, what is being deprecated in version 3 are the paths where the SDK
+handled a username and password to obtain the user's API key for forward
+operations.  Users may still operate with an API key by retrieving it from the
+Planet user interface under [My Settings](https://www.planet.com/account/#/user-settings)
+and providing it to the SDK.  While API keys remain supported for machine-to-machine
+API use cases using `api.planet.com` APIs, OAuth2 mechanisms should be preferred
+where the use case allows for it.
+
+Users may also continue to initialize SDK and CLI sessions with their username
+and password, but rather than being processed by the SDK itself a browser must
+be invoked to complete OAuth2 client session initialization.
+This new method is intended to offer a number of long term benefits, including:
+
+* The new method provides the SDK and the CLI with access tokens that may be
+  used with both `api.planet.com` and `services.sentinel-hub.com` endpoints.  The method
+  used by version 2 of the SDK was specific to `api.planet.com` endpoints, and
+  will never be supported by `services.sentinel-hub.com` endpoints.
+* The new method extends (currently optional) multifactor authentication (MFA)
+  to SDK and CLI client use cases.
+* The new method is compatible with other platform enhancements currently under
+  development by Planet's software engineering team.
+
+For complete details on the new mechanisms, see the [Client Authentication Guide](../python/sdk-client-auth.md).
+
+### CLI Usage
+The [`planet auth`](../../cli/cli-reference/#auth) command has been substantially
+revised to align to the new authentication mechanisms.  For migration from version 2
+of the SDK, the following changes are the most important to note:
+
+* The `planet auth init` command has been replaced with [`planet auth login`](../../cli/cli-reference/#login).
+  By default, this command will open a browser window to allow the user to log
+  in to their Planet account and authorize the SDK or CLI to access their account.
+  Other options are available to support a variety of use cases, including a
+  `--no-open-browser` option for remote shells.  See `planet auth login --help`
+  for complete details.
+* The `planet auth value` command has been deprecated.  Depending on whether the SDK
+  has been initialized with OAuth2 or API key authentication,
+  [`planet auth print-access-token`](../../cli/cli-reference/#print-access-token)
+  or [`planet auth print-api-key`](../../cli/cli-reference/#print-api-key) may
+  be used.  OAuth2 sessions should be preferred where possible.
+* The `planet auth store` command has been deprecated. The various options to the
+  `planet auth login` command should provide suitable alternatives for all use cases.
+  OAuth2 sessions should be favored for user interactive use cases, such as CLI usage.
+  `planet auth login --auth-api-key YOUR_API_KEY` may be used to initialize the SDK
+  with API key based authentication where the use case requires it.
+
+### Session Persistence
+Both version 2 and version 3 of the SDK use the `~/.planet.json` file in the user's
+home directory to store user's API key.  If this file is present and was configured
+by version 2 of the SDK, it should continue to work.
+
+While the `~/.planet.json` file continues to be used by version 3, and version 3
+understands files written by version 2, version 3 will not write the same information
+to this file that version 2 did.  Version 3 uses this file in conjunction with the
+`~/.planet` directory and subdirectories to store OAuth2 tokens and additional
+session information needed for a smooth user experience.
+
+Version 3 of the SDK provides a [`planet auth reset`](../../cli/cli-reference/#reset)
+command to reset all saved state should it become corrupted.  When this command is run,
+the old files are moved aside rather than deleted.
+
+### SDK Session Initialization
+See the [Client Authentication Guide](../python/sdk-client-auth.md) for a complete
+discussion of all options now available.
+
+Basic SDK use cases should work with no alterations.
+User sessions initialized by [`planet auth login`](../../cli/cli-reference/#login)
+will be detected by an application using a default Planet client when
+run in an environment with access to the user's home directory.  For example:
+
+```python linenums="1"
+{% include 'auth-session-management/cli_managed_auth_state__implicit.py' %}
+```
+
+Applications may also continue to initialize the SDK with a specific API key as follows:
+```python linenums="1"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__api_key.py' %}
+```
+
+Users developing new applications should consult the [Client Authentication Guide](../python/sdk-client-auth.md)
+for a complete discussion of all OAuth2 based mechanisms.  OAuth2 mechanisms
+should be preferred to the use of Planet API keys.
+
+----