Merge pull request #436 from calibreapp/update-command-descriptions

Update command descriptions (CAL-397)

CHANGELOG.md

@@ -1,3 +1,13 @@
+# 5.01 (2022-05-13)
+## 🚩 Commands and flags
+* Adds a new command: `calibre team list` to list all Teams depending on API Token in use.
+
+## 🛠 Core
+* Updates all command and flag descriptions for clarity and accuracy.
+
+## 📖 Documentation
+* updates `README.md` to include link to Calibre’s documentation page for all CLI commands
+
 # 5.0.0 (2022-04-29)
 
 ## 💥 Breaking changes

README.md

@@ -65,7 +65,7 @@ $ calibre --help
 $ calibre <command> --help
 ```
 
-or [see all commands](CLI_COMMANDS.md) in this repository.
+or [see all commands](CLI_COMMANDS.md) in this repository or [Calibre’s documentation](https://calibreapp.com/docs/automation/cli-commands).
 
 In Node, you can use the either ES Modules or CommonJS versions accordingly:
 

__tests__/cli/__snapshots__/index.test.js.snap

@@ -5,15 +5,23 @@ exports[`calibre --help 1`] = `
 
 Commands:
 
-  calibre site <command>   Site management commands
-  calibre test <command>   Single page tests
-  calibre connection-list  Print a list of connection speeds
-  calibre device-list      Print a list of test devices
-  calibre location-list    Print a list of test locations
-  calibre metric-list      Print a list of metrics
-  calibre token <command>  Store or revoke a Calibre API token (Use instead of C
-                           ALIBRE_API_TOKEN environment variable)
-  calibre request          Make a request to the Calibre GraphQL API
+  calibre site <command>   Use the site command to manage your Sites, Pages, Tes
+                           t Profiles, Deploys, Snapshots and download the monit
+                           oring data.
+  calibre team <command>   Use the team command to manage Teams.
+  calibre test <command>   Use the test command to run Single Page Tests: public
+                            or private tests for a single Page tested from a sin
+                           gle device. This command also supports viewing all Si
+                           ngle Page Tests and retrieving their artifacts.
+  calibre connection-list  List all available network connection speeds.
+  calibre device-list      List all available test devices.
+  calibre location-list    List all available test locations.
+  calibre metric-list      List all available web performance metrics.
+  calibre token <command>  Use the token command to store or revoke a Calibre AP
+                           I token. You can also save your token with the CALIBR
+                           E_API_TOKEN environment variable.
+  calibre request          Use the request command to make a request to the Cali
+                           bre GraphQL API.
 
 Options:
 

__tests__/cli/__snapshots__/request.test.js.snap

@@ -7,18 +7,14 @@ exports[`request missing query argument 1`] = `
 
  calibre request
 
-Make a request to the Calibre GraphQL API
+Use the request command to make a request to the Calibre GraphQL API.
 
 Options:
 
   --help       Show help                                               [boolean]
   --version    Show version number                                     [boolean]
-  --query      GraphQL query to execute. e.g.:
-
-               calibre request --query='query G
-               etSite($slug: String!) {organisation{site(slug: $slug){slug}}}' -
-               -slug=calibre                                 [string] [required]
-  --variables  Pass query variables as named arguments"
+  --query      Pass a GraphQL query to execute.              [string] [required]
+  --variables  Pass query variables as named arguments."
 `;
 
 exports[`request returns response 1`] = `

__tests__/cli/__snapshots__/site.test.js.snap

@@ -7,16 +7,19 @@ exports[`missing site argument 1`] = `
 
  calibre site pages [options]
 
-Print a list of pages for a given site
+List Pages for a selected Site.
 
 Options:
 
   --help     Show help                                                 [boolean]
   --version  Show version number                                       [boolean]
-  --site     The identifying slug of a site                  [string] [required]
-  --count    The number of records to return, maximum: 500         [default: 25]
+  --site     A unique slug identifying each Site. You can find it in Site Settin
+             gs → General or by using the calibre site list command.
+                                                             [string] [required]
+  --count    The number of items to return (default: 25, maximum: 500).
+                                                                   [default: 25]
   --cursor   The cursor to fetch records after
-  --json     Output in JSON format"
+  --json     Outputs the results of the command in JSON format."
 `;
 
 exports[`missing site argument value 1`] = `
@@ -26,14 +29,17 @@ exports[`missing site argument value 1`] = `
 
  calibre site pages [options]
 
-Print a list of pages for a given site
+List Pages for a selected Site.
 
 Options:
 
   --help     Show help                                                 [boolean]
   --version  Show version number                                       [boolean]
-  --site     The identifying slug of a site                  [string] [required]
-  --count    The number of records to return, maximum: 500         [default: 25]
+  --site     A unique slug identifying each Site. You can find it in Site Settin
+             gs → General or by using the calibre site list command.
+                                                             [string] [required]
+  --count    The number of items to return (default: 25, maximum: 500).
+                                                                   [default: 25]
   --cursor   The cursor to fetch records after
-  --json     Output in JSON format"
+  --json     Outputs the results of the command in JSON format."
 `;

__tests__/cli/__snapshots__/team.test.js.snap

@@ -0,0 +1,23 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`missing subcommand 1`] = `
+"
+
+ Not enough non-option arguments: got 0, need at least 1 
+
+ calibre team <command>
+
+Use the team command to manage Teams.
+
+Commands:
+
+  calibre team list  List Teams based on API Token access. For Admin Tokens, thi
+                     s will list all teams or as specified based on your setting
+                     s. For Personal Access Tokens, this will list Teams that yo
+                     u have access to.
+
+Options:
+
+  --help     Show help                                                 [boolean]
+  --version  Show version number                                       [boolean]"
+`;

__tests__/cli/site/__snapshots__/delete-deploy.test.js.snap

@@ -12,14 +12,16 @@ exports[`site delete-deploy requires uuid 1`] = `
 
  calibre site delete-deploy [options]
 
-Deletes a deploy from a site
+Delete a deploy from a selected Site.
 
 Options:
 
   --help     Show help                                                 [boolean]
   --version  Show version number                                       [boolean]
-  --site     The identifying slug of a site                  [string] [required]
-  --uuid     The uuid of the deploy                                   [required]
-  --confirm  Confirm the deletion
-  --json     Output in JSON format"
+  --site     A unique slug identifying each Site. You can find it in Site Settin
+             gs → General or by using the calibre site list command.
+                                                             [string] [required]
+  --uuid     The UUID of the deploy.                                  [required]
+  --confirm  Use this flag to confirm the deletion of the selected deploy.
+  --json     Outputs the results of the command in JSON format."
 `;

__tests__/cli/site/__snapshots__/delete-snapshot.test.js.snap

@@ -12,14 +12,16 @@ exports[`site delete-snapshot requires id 1`] = `
 
  calibre site delete-snapshot [options]
 
-Deletes a snapshot from a site
+Delete a Snapshot from a selected Site.
 
 Options:
 
   --help     Show help                                                 [boolean]
   --version  Show version number                                       [boolean]
-  --site     The identifying slug of a site                  [string] [required]
-  --id       The id of the snapshot                                   [required]
-  --confirm  Confirm the deletion
-  --json     Output in JSON format"
+  --site     A unique slug identifying each Site. You can find it in Site Settin
+             gs → General or by using the calibre site list command.
+                                                             [string] [required]
+  --id       The id of the Snapshot.                                  [required]
+  --confirm  Use this flag to confirm the deletion of the selected Snapshot.
+  --json     Outputs the results of the command in JSON format."
 `;

__tests__/cli/site/__snapshots__/get-snapshot-metrics.test.js.snap

@@ -9,14 +9,16 @@ exports[`snapshot metrics returns no snapshot error 1`] = `
 
  calibre site get-snapshot-metrics [options]
 
-Get the metrics of a given snapshot
+Get all metrics of a given Snapshot.
 
 Options:
 
   --help      Show help                                                [boolean]
   --version   Show version number                                      [boolean]
-  --site      The identifying slug of a site                 [string] [required]
-  --snapshot  The identifying id of a snapshot                        [required]
-  --json      Output in JSON format
-  --csv       Output in CSV format"
+  --site      A unique slug identifying each Site. You can find it in Site Setti
+              ngs → General or by using the calibre site list command.
+                                                             [string] [required]
+  --snapshot  The id of a Snapshot.                                   [required]
+  --json      Outputs the results of the command in JSON format.
+  --csv       Outputs the results of the command in CSV format."
 `;

__tests__/cli/team.test.js

@@ -0,0 +1,6 @@
+import { runCLI } from '../utils'
+
+test('missing subcommand', async () => {
+  const out = await runCLI({ args: 'team', testForError: true })
+  expect(out).toMatchSnapshot()
+})

__tests__/cli/team/__snapshots__/list.test.js.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`team list lists all teams 1`] = `
+"2 sites
+SLUG        | NAME     | DESCRIPTION     
+calibre     | Calibre  | Default team    
+engineering | Monitors | Engineering team"
+`;

__tests__/cli/team/list.test.js

@@ -0,0 +1,19 @@
+import {
+  runCLI,
+  setupIntegrationServer,
+  teardownIntegrationServer
+} from '../../utils'
+
+import listTeams from '../../fixtures/listTeams.json'
+
+describe('team list', () => {
+  beforeAll(() => setupIntegrationServer(listTeams))
+  afterAll(() => teardownIntegrationServer())
+
+  test('lists all teams', async () => {
+    const out = await runCLI({
+      args: 'team list'
+    })
+    expect(out).toMatchSnapshot()
+  })
+})

__tests__/cli/token/__snapshots__/set.test.js.snap

@@ -7,13 +7,15 @@ exports[`missing token argument 1`] = `
 
  calibre token <command>
 
-Store or revoke a Calibre API token (Use instead of CALIBRE_API_TOKEN environmen
-t variable)
+Use the token command to store or revoke a Calibre API token. You can also save
+your token with the CALIBRE_API_TOKEN environment variable.
 
 Commands:
 
-  calibre token set <key>  Set the Calibre API token used for CLI commands
-  calibre token remove     Remove the Calibre API token used for CLI commands
+  calibre token set <token>  Store your API Token to use the CLI (saved in ~/.co
+                             nfig/configstore/calibre.json).
+  calibre token remove       Remove the saved API Token used for CLI commands (f
+                             rom ~/.config/configstore/calibre.json).
 
 Options:
 

__tests__/fixtures/listTeams.json

@@ -0,0 +1,18 @@
+{
+  "data": {
+    "organisation": {
+      "teams": [
+        {
+          "name": "Calibre",
+          "description": "Default team",
+          "slug": "calibre"
+        },
+        {
+          "name": "Monitors",
+          "description": "Engineering team",
+          "slug": "engineering"
+        }
+      ]
+    }
+  }
+}

generate-cli-md.js

@@ -9,14 +9,19 @@ ${describe || ''}
 }
 
 const formatOptions = options => {
-  return `Options:
- ${Object.keys(options).map(key => {
+  const optionKeys = Object.keys(options)
+  if (!optionKeys.length) {
+    return ''
+  } else {
+    return `Flags:
+ ${optionKeys.map(key => {
    const { describe, default: defaultValue, type } = options[key]
    return `
-  * \`${key}\`: ${describe}${
+  * \`--${key}\`: ${describe}${
      defaultValue ? ` (default: \`${defaultValue}\`)` : ''
    }${type ? ` (${type})` : ''}`
  })}`
+  }
 }
 
 const template = command => {
@@ -42,8 +47,6 @@ const template = command => {
 
 const commands = getCommandMetaData()
 
-// console.log(JSON.stringify(commands, null, 2))
-
 let output = ''
 
 commands.forEach(command => {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "calibre",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "engines": {
     "node": ">= 14.18"
   },

src/api/team.js

@@ -0,0 +1,20 @@
+import { request } from './graphql.js'
+
+const LIST_QUERY = `
+  query {
+    organisation {
+      teams {
+        name
+        description
+        slug
+      }
+    }
+  }
+`
+
+const list = async () => {
+  const response = await request({ query: LIST_QUERY })
+  return response.organisation.teams
+}
+
+export { list }

src/cli-commands.js

@@ -4,11 +4,13 @@ import * as LocationList from './cli/location-list.js'
 import * as MetricList from './cli/metric-list.js'
 import * as Request from './cli/request.js'
 import * as Site from './cli/site.js'
+import * as Team from './cli/team.js'
 import * as Test from './cli/test.js'
 import * as Token from './cli/token.js'
 
 const commands = [
   Site,
+  Team,
   Test,
   ConnectionList,
   DeviceList,