@jacebenson/jsn 0.0.8 → 0.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -139,4 +139,6 @@ export const cli = yargs(hideBin(process.argv))
   .version(false)
   .strictCommands()
   .strictOptions(false)
-  .epilogue('LEARN MORE\n  Use "jsn <command> --help" for more information about a command.');
+  .epilogue('TIPS\n'
+    + '  --query is available on every list command (e.g. "incidents list --query priority=1")\n'
+    + '  Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options');

package/src/commands/_ticket.js

@@ -9,7 +9,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
   return {
     command: `${displayName} [subcommand]`,
     aliases: [table, alias],
-    describe: `Manage ${displayName}`,
+    describe: `Manage ${displayName} (e.g. "${displayName} list --query priority=1")`,
     builder: (yargs) => {
       return yargs
         .command({
@@ -17,8 +17,8 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           aliases: ['ls'],
           describe: `List ${table}`,
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { alias: 'o', type: 'number', default: 0, describe: 'Offset for pagination' }),
           handler: wrap(async (argv, app) => {

package/src/commands/dev/_generic.js

@@ -61,8 +61,8 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         aliases: ['ls'],
         describe: `List ${name}`,
         builder: (y) => y
-          .option('query', { type: 'string', describe: 'Encoded query string' })
-          .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+          .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true^priority=1")' })
+          .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "name,label,super_class")' })
           .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
         handler: wrap(async (argv, app) => {
           const columns = argv.columns ? argv.columns.split(',') : defaultColumns;
@@ -123,7 +123,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         .command({
           command: 'create',
           describe: `Create a new ${singular}`,
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON data' }),
+          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2"}\')' }),
           handler: wrap(async (argv, app) => {
             const recordData = JSON.parse(argv.data);
             const record = await app.sdk.create(table, recordData);
@@ -138,7 +138,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         .command({
           command: 'update <identifier>',
           describe: `Update ${vowelArticle(singular)} ${singular}`,
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON data' }),
+          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2"}\')' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
             const queryField = isHexString(id) && id.length === 32 ? 'sys_id' : 'name';
@@ -213,7 +213,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
   return {
     command: `${name} [subcommand]`,
     aliases: aliases || [],
-    describe: `Manage ${name}`,
+    describe: `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
     builder,
     handler: (argv) => {
       if (argv.help) return;

package/src/commands/dev/flows.js

@@ -12,8 +12,8 @@ export function flowsCmd(wrap) {
           aliases: ['ls'],
           describe: 'List flows',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'active', 'description', 'sys_created_by', 'sys_updated_on'];

package/src/commands/dev/logs.js

@@ -12,8 +12,8 @@ export function logsCmd(wrap) {
           aliases: ['ls'],
           describe: 'List system logs',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['level', 'message', 'source', 'created'];

package/src/commands/dev/scopes.js

@@ -12,8 +12,8 @@ export function scopesCmd(wrap) {
           aliases: ['ls'],
           describe: 'List application scopes',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'scope', 'short_description', 'active'];

package/src/commands/dev/updatesets.js

@@ -12,8 +12,8 @@ export function updateSetsCmd(wrap) {
           aliases: ['ls'],
           describe: 'List update sets',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'state', 'application'];

package/src/commands/groupmembers.js

@@ -12,8 +12,8 @@ export function groupMembersCmd(wrap) {
           aliases: ['ls'],
           describe: 'List group members',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['user.name', 'group.name'];

package/src/commands/grouproles.js

@@ -12,8 +12,8 @@ export function groupRolesCmd(wrap) {
           aliases: ['ls'],
           describe: 'List group roles',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['group.name', 'role.name'];

package/src/commands/groups.js

@@ -12,8 +12,8 @@ export function groupsCmd(wrap) {
           aliases: ['ls'],
           describe: 'List groups',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['name', 'manager', 'email'];

package/src/commands/records.js

@@ -22,7 +22,7 @@ function getDefaultColumns(table) {
 export function recordsCmd(wrap) {
   return {
     command: 'records <subcommand>',
-    describe: 'Query and manage records in any table',
+    describe: 'Query and manage records in any table (e.g. "records list --table incident --query priority=1")',
     builder: (yargs) => {
       return yargs
         .command({
@@ -30,8 +30,8 @@ export function recordsCmd(wrap) {
           describe: 'List records from a table',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { type: 'number', default: 0, describe: 'Offset' }),
           handler: wrap(async (argv, app) => {
@@ -80,7 +80,7 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
-            .option('columns', { type: 'string', describe: 'Comma-separated columns' }),
+            .option('columns', { type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' }),
           handler: wrap(async (argv, app) => {
             const params = new URLSearchParams();
             params.set('sysparm_query', `sys_id=${argv['sys-id']}`);
@@ -99,7 +99,7 @@ export function recordsCmd(wrap) {
           describe: 'Create a new record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data' }),
+            .option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2"}\')' }),
           handler: wrap(async (argv, app) => {
             const recordData = JSON.parse(argv.data);
             const record = await app.sdk.create(argv.table, recordData);
@@ -112,7 +112,7 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data' }),
+            .option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2"}\')' }),
           handler: wrap(async (argv, app) => {
             const recordData = JSON.parse(argv.data);
             const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);

package/src/commands/tickets.js

@@ -4,7 +4,7 @@ export function ticketsCmd(wrap) {
   return {
     command: 'tickets [subcommand]',
     aliases: ['ticket'],
-    describe: 'Query generic tickets',
+    describe: 'Query generic tickets (e.g. "tickets list --query active=true")',
     builder: (yargs) => {
       return yargs
         .command({
@@ -12,8 +12,8 @@ export function ticketsCmd(wrap) {
           aliases: ['ls'],
           describe: 'List tickets',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "active=true^priority=1")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description,priority")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { alias: 'o', type: 'number', default: 0, describe: 'Offset' }),
           handler: wrap(async (argv, app) => {
@@ -73,7 +73,7 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON data' }),
+          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
           handler: wrap(async (argv, app) => {
             const recordData = JSON.parse(argv.data);
             const record = await app.sdk.create('ticket', recordData);
@@ -83,7 +83,7 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON data' }),
+          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
           handler: wrap(async (argv, app) => {
             const recordData = JSON.parse(argv.data);
             const findParams = new URLSearchParams();

package/src/commands/users.js

@@ -12,8 +12,8 @@ export function usersCmd(wrap) {
           aliases: ['ls'],
           describe: 'List users',
           builder: (y) => y
-            .option('query', { type: 'string', describe: 'Encoded query string' })
-            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns' })
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
+            .option('columns', { alias: 'c', type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['user_name', 'name', 'email', 'active'];