GAGE - SAGE Command Line Interface
To make authenticated programmatic access to our file server easier, we have developed a Python Command Line Interface (CLI) client that, along with a bash-like shell, can initiate the initial browser authentication used to log in, obtain the proper tokens on your computer/device, and automatically manage (refresh) your tokens for you to facilitate unattended authenticated script access to our file server.
With our new Identity Management (IdM) for data file server access, our users will need to update their data access scripts to include the authentication needed to access the file server.
First, register with us, if you haven't already, before continuing through this document. For more examples of accessing our HTTP file server see our File Server Access Examples.
Installing the Python CLI client
Requirements: Python 3.7+ and a bash-like shell (see bash for Windows).
- (Optional) We recommend using a Python Virtual Environment:
$ python3 -m venv venv
$ . venv/bin/activate
- Install the CLI:
$ pip install earthscope-cli
Using the EarthScope CLI
- Check the CLI’s help file to see options:
$ es sso --help
- Set up the CLI with your user profile:
- To use the CLI, you must first perform a one-time authentication step in a web browser to log in to your EarthScope (UNAVCO/IRIS) account and confirm your device code:
$ es sso login
- If you are on a computer without a web browser configured, copy the URL from the command output that is displayed to use in a browser on your personal computer or mobile device to log in and confirm your device code. Note: if you see an error in your terminal about not being able to open the URL, ignore it, as you will be using a separate browser to open the URL.
- If you are on your a computer with a web browser configured, this command will automatically launch your browser for you to log in and confirm your device code.
- This will complete your authentication and will issue you an Access token that will be automatically stored by the CLI, in the background, for your ongoing script access.
- Note: CLI managed tokens expire after 30 days of no use. If your token expires, you will need to repeat the previous authentication step to receive new tokens. To avoid this, make sure your script runs the following command at least once every 30 days, e.g., using cron.
- Note: ignore the notice "NO TOKEN VALIDATION IMPLEMENTED". It will be removed in upcoming releases.
- To display your access token and automatically refresh it, issue the following CLI command:
$ es sso access --token
Note: The above CLI command can be handily used with shell Command Substitution, as shown below, to make authenticated/authorized access simple, without the need to manually store, copy, or otherwise manage your tokens.
Note: To write your access token to a file for re-use apart from the CLI's python environment, you can re-direct the command output to a file:
$ es sso access --token > mytoken
Note: your access token is stored on your system at the path shown with the following command:
$ es sso state --path
- Access files:
- Use the cURL command below that uses the CLI (via Command Substitution) to automatically insert your access token to log in to the UNAVCO Data File Server:
$ curl -L -O --url https://data-idm.unavco.org/archive/gnss/rinex/obs/1992/001/algo0010.92d.Z --header "authorization: Bearer $(es sso access --token)"
- Use the Wget command below that uses the CLI (via Command Substitution) to automatically insert your access token to log in to the UNAVCO Data File Server:
$ wget https://data-idm.unavco.org/archive/gnss/rinex/obs/2022/060/p1230600.22d.Z --header "authorization: Bearer $(es sso access --token)"
See python pycurl example that uses the CLI: python-pycurl-cli-example.py.
- For more examples see our File Server Access Examples.
Last modified: 2022-11-15 15:11:16 America/Denver