v0.1.0

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: release
+on: 
+  push:
+    tags:
+      - v*
+  workflow_dispatch:
+
+env:
+  GO_VERSION: 1.21.0
+
+jobs:
+  release:
+    name: Release
+    strategy:
+      matrix:
+        platform: [ubuntu-latest]
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ env.GO_VERSION }}
+        id: go
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Cache Go modules
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v4
+        with:
+          version: latest
+          args: release -f .goreleaser.yml --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1 @@
+.DS_Store

.goreleaser.yml

@@ -0,0 +1,46 @@
+# .goreleaser.yml
+release:
+  github:
+    owner: openaq
+    name: openaq-cli
+
+snapshot:
+  name_template: SNAPSHOT-{{ .Commit }}
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - windows
+      - darwin
+      - freebsd
+    goarch:
+      - amd64
+      - arm64
+    goarm:
+      - 6
+      - 7
+    ignore:
+      - goos: windows
+        goarch: arm64
+      - goos: windows
+        goarch: arm
+      - goos: freebsd
+        goarch: arm
+    dir: .
+    main: .
+    binary: openaq
+    flags:
+      - -trimpath
+    ldflags:
+      - -X github.com/openaq/openaq-cli/cmd/version.Version={{.Version}}
+      - -s -w 
+
+checksum:
+  algorithm: sha256
+  name_template: '{{ .ProjectName }}-{{ .Version }}-checksums.txt'

LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2023 OpenAQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,203 @@
+
+# OpenAQ API Command Line Client
+
+A command line utility to interact with the OpenAQ API.
+
+
+## Installation
+
+> The OpenAQ CLI tool is still a *work in progress* and may be unstable until a 1.0 release. 
+
+
+With Golang > 1.18 installed run:
+
+```
+go install github.com/openaq/openaq-cli
+```
+
+In future releases we will release pre-compiled executables for Windows, Mac and Linux.
+
+## Usage
+
+> Note: An OpenAQ API Key is required to use the OpenAQ CLI. Registering for an API Key is free and only requires a valid email address. Register at https://api.openaq.org/register
+
+
+To set your API Key run: 
+
+```sh
+openaq configure api-key set my-super-secret-openaq-api-key-1234-5678
+```
+
+replacing `my-super-secret-openaq-api-key-1234-5678` with your API Key
+
+
+### Global flags
+
+`--config` `-c` — Manually set a configuration TOML file, default is $HOME/.openaq.toml
+
+`--help` `-h` — returns helps for any command
+
+### Resource flags 
+
+`--json` - Returns data as JSON instead of the default table view.
+
+`--pretty` - Only used in combination with `--json`. Provides a "pretty" indented and syntax highlighted view of the JSON output
+
+`--csv` - Returns the result as a csv (comma separated values).
+
+
+_the following only work on resource `list` calls_
+
+`--limit` - takes an integer to limit the number of results to return.
+
+`--page` - takes an integer to set the page number for API pagination
+
+### Commands
+
+configure 
+---
+__api-key__
+
+```sh
+openaq configure api-key set [api-key]
+```
+
+countries
+---
+```sh
+openaq countries list 
+```
+
+Provides a list of countries.
+
+
+```sh
+openaq countries get [countriesID]
+```
+
+Provides a single country given a countriesID
+
+
+help
+---
+```
+openaq help
+```
+
+Provides a help guide with commands
+
+
+locations
+---
+```sh
+openaq locations list 
+```
+
+Provides a list of locations.
+
+__flags__
+
+`--countries` - filter locations by one or more comma-delimited `countries ID` e.g. 1,2,3
+
+`--providers` - filter locations by one or more comma-delimited `providers ID` e.g. 1,2,3
+
+
+```sh
+openaq locations get [locationsID]
+```
+
+Provides a single location given a locationsID
+
+
+manufacturers
+---
+
+Coming soon
+
+measurements
+---
+
+```sh
+openaq measurements list [locationsID]
+```
+
+Provides a list of measurements for a given locationsID
+
+
+__flags__
+
+`--to` - a date in form YYYY-MM-DD to filter measurements as the end date of the period e.g. 2023-08-23
+
+`--from` -  a date in form YYYY-MM-DD to filter measurements as the start date of the period e.g. 2023-08-23
+
+`--parameters` - filter measurements by one or more comma-delimited `parameters ID` e.g. 1,2,3
+
+`--mini` - provides a miniature/simplified version of the measurements resource including only the parameter name, datetime in UTC, datetime in local, measurement period, and value 
+
+
+owners
+---
+Coming soon
+
+parameters
+---
+
+```sh
+openaq parameters list 
+```
+Provides a list of parameters.
+
+
+__flags__
+
+`--type` - filter parameters by `parameterType` either `pollutant` or `meteorological`
+
+```sh
+openaq parameters get [parametersID]
+```
+Provides a single parameter for a given parametersID
+
+
+version 
+---
+```
+openaq version
+```
+
+prints the version of the OpenAQ CLI
+
+
+## Examples
+
+Get measurements for location 2178 between 2023-08-01 and 2023-08-07 and return the results as a csv.
+
+```sh
+openaq measurements list 2178 --from 2023-08-01 --to 2023-08-07 --csv
+```
+
+Get measurements for location 2178 between 2023-08-01 and 2023-08-07 and limit to only PM2.5 return the results as a csv.
+
+```sh
+openaq measurements list 2178 --from 2023-08-01 --to 2023-08-07 --parameters 2 --csv
+```
+
+Get locations only from provider_id 166 (Clarity) 
+
+```sh
+openaq locations list --provider 166
+```
+
+### Configuration file
+
+The OpenAQ CLI requires a configuration file to store and access certain variables on the local file system. The first time `openaq` is run a file named `.openaq.toml` will be created in the `$HOME` directory of your system.
+
+
+> The configuration file specification is not yet feature complete, changes to the specification will likely occur in future releases.
+
+`.openaq.toml` format:
+
+```toml
+api-key = ''
+```
+
+

cmd/configure/configure.go

@@ -0,0 +1,40 @@
+package configure
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+)
+
+func init() {
+	apiKeyCmd.AddCommand(setApiKeyCmd)
+	ConfigureCmd.AddCommand(apiKeyCmd)
+}
+
+var ConfigureCmd = &cobra.Command{
+	Use:   "configure",
+	Short: "Modify configuration file",
+	Long:  ``,
+}
+
+var apiKeyCmd = &cobra.Command{
+	Use:   "api-key",
+	Short: "Set the api-key configuration value",
+	Long:  ``,
+}
+
+var setApiKeyCmd = &cobra.Command{
+	Use:   "set",
+	Short: "Set the api-key configuration value",
+	Long:  ``,
+	Args:  cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		viper.Set("api-key", args[0])
+		err := viper.WriteConfig()
+		if err != nil {
+			fmt.Println("Cannot find configuration file")
+		}
+		fmt.Println("API Key configuration set")
+	},
+}