"oci session authenticate" user experience is confusing

I followed these instructions: https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm

I authenticated successfully, and oci session validate succeeds. However, any API interaction results in the error:

ERROR: The config file at ~/.oci/config is invalid:

+Config Errors---+----------------------------------------------------------------------------+
| Key  | Error   | Hint                                                                       |
+------+---------+----------------------------------------------------------------------------+
| user | missing | log into the console and go to the user's settings page to find their OCID |
+------+---------+----------------------------------------------------------------------------+

The user key is indeed missing from ~/.oci/config. Running oci session refresh did not add it.

There are a total of two google results for this error, and neither were useful - opened this issue to hopefully get this resolved, and add a google result for anyone else who hit this. After figuring out how to find my OCID from the console and adding it manually to ~/.oci/config, then trying an API interaction, I got a new error message:

WARNING: The active profile contains a value for 'security_token_file' which is not being used. To authenticate using the token, specify --auth security_token

This showed me that I had misunderstood the instructions at the bottom, where the --auth security_token parameter was mentioned as necessary for all CLI interactions using this auth. This was a confusing experience because page reads like two alternatives - authenticating with a browser and without. I chose the former, and proceeded to the next page of instructions - missing that critical step.

Several suggestions for resolving this:

1. Make it extremely clear in the docs that that parameter is required.
2. For that error message case, if security_token_file is present in the profile, include an additional (did you forgot to pass '--auth security_token'?) message (or something like that).
3. Add a configuration option that has the same effect as --auth security_token, and set that when a profile is created using oci session validate.

Start by reviewing the OCI session authentication documentation linked in the issue and the CLI handling of oci session authenticate, oci session validate, and oci session refresh. Reproduce the missing user error and the unused security_token_file warning; done should mean the required --auth security_token flow and the next steps are clear to users, either through documentation or improved CLI guidance.