Package: earthscope-cli
EarthScope CLIA Typer CLI for authenticating with the EarthScope APIGetting StartedRequirementsInstallation[Use the CLI with your user profile](#Use the CLI with your user profile)Example - Retrieve a file from the UNAVCO Data File ServercURLWgetFAQ/troubleshootingGetting StartedRequirementsTo use the CLI you must have:Registered an account with Earthscope (sign up now!). Seeherefor more informationPython >= 3.7A bash-like shell (seebash for windows)Installation(Optional) Suggest setting up and activating a python virtual environment so as to not clutter your system pythonpython3-mvenvvenv
.venv/bin/activateInstall the CLI:pipinstallearthscope-cliUse the CLI. The package has aconsole_scriptssection which makes a shortcut calledesavailable in your python environment.es--helpUse the CLI with your user profileLogin to EarthScope with Device Authorization Flow:esssologinThis will prompt your browser to open a device confirmation page with the same code displayed in the url shown on your command line.
If you are on a device that does not have a web browser, you can copy the displayed url in a browser on another device (personal computer, mobile device, etc...)
and complete the confirmation there.Thelogincommand will save your token locally. If this token is deleted, you will need to re-authenticate (login) to retrieve your token again.
Run the following command to see where your token is stored:esssostate--pathget/refresh your access tokenesssoaccess--tokenTheaccesscommand will display your access token. If your access token is close to expiration or expired,
the default behavior is to automatically refresh your token.If you want to manually refresh your token:esssorefreshNever share your tokens. If you think your token has been compromised, please revoke your refresh token and re-authenticate (login):esssorefresh--revoke
esssologinGet your user profile from theuser-management-apirunning behindhttps://data.unavco.org/user/profile/esusergetExplore the CLIUse--helpon any command to see more information on available commands and options.es--help
essso--help
esaccess--help
.
.Example: Retrieve a file from the UNAVCO Data File Server with cURL or WgetStep 1: login. This step is only required once (the first time you run the cli on your device) unless your access token is deleted from your device.Step 2: Retrieve your token usinges sso access --token. Add this access token as an Authorization header with your cURL or Wget command.Example using cURL:curl-L-O-f--urlhttps://data.unavco.org/archive/gnss/rinex/obs/1992/001/algo0010.92d.Z--header"authorization: Bearer$(esssoaccess--token)"where-L : follow redirects-O : uses server filename-f : (HTTP) Fail on error without server output. Error code 22 -- good for scriptingMake sure to include the -f or it will be difficult to tell if an error occured.Example using Wget:wgethttps://data.unavco.org/archive/gnss/rinex/obs/2022/060/p1230600.22d.Z--header"authorization: Bearer$(esssoaccess--token)"See morefile server access examplesIf you would like to access files using python - please check out theearthscope-sdkFAQ/troubleshootingHow long does my access token last?Your access token lasts 8 hours. Once it is expired, your refresh token will need to be used to refresh your access token.How long does my refresh token last?Your refresh token will never expire - unless you are inactive (do not use it) for one year.
If it does expire, you will need to re-authenticate to get a new access and refresh token.What is a refresh token and how does the CLI use it?A refresh token is a special token that is used to renew your access token without you needing to log in again.
The refresh token is obtained from your access token, and using thees sso accesscommand will automatically
renew your access token if it is close to expiration. You can 'manually' refresh your access token by using the commandes sso refresh.
If your access token is compromised, you can revoke your refresh token usinges sso refresh --revoke. Once your access token expires,
it can no longer be renewed and you will need to re-login.Should I hard-code my access token into my script?No. We recommend you use the cli commands to retrieve your access tokens in your scripts.
This way your access token will not be compromised by anyone viewing your script.
The access token only lasts 8 hours and cannot be used afterwards unless refreshed.