@hesed/psql 0.4.1 → 0.5.1

package/README.md

@@ -26,7 +26,7 @@ $ npm install -g @hesed/psql
 $ pg COMMAND
 running command...
 $ pg (--version)
-@hesed/psql/0.4.1 linux-x64 node-v24.16.0
+@hesed/psql/0.5.1 linux-x64 node-v24.17.0
 $ pg --help [COMMAND]
 USAGE
   $ pg COMMAND
@@ -80,7 +80,7 @@ EXAMPLES
   $ pg psql auth add -p prod
 ```
 
-_See code: [src/commands/psql/auth/add.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/auth/add.ts)_
+_See code: [src/commands/psql/auth/add.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/auth/add.ts)_
 
 ## `pg psql auth delete`
 
@@ -105,7 +105,7 @@ EXAMPLES
   $ pg psql auth delete -p prod
 ```
 
-_See code: [src/commands/psql/auth/delete.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/auth/delete.ts)_
+_See code: [src/commands/psql/auth/delete.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/auth/delete.ts)_
 
 ## `pg psql auth list`
 
@@ -125,7 +125,7 @@ EXAMPLES
   $ pg psql auth list
 ```
 
-_See code: [src/commands/psql/auth/list.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/auth/list.ts)_
+_See code: [src/commands/psql/auth/list.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/auth/list.ts)_
 
 ## `pg psql auth profile`
 
@@ -150,7 +150,7 @@ EXAMPLES
   $ pg psql auth profile --default test
 ```
 
-_See code: [src/commands/psql/auth/profile.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/auth/profile.ts)_
+_See code: [src/commands/psql/auth/profile.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/auth/profile.ts)_
 
 ## `pg psql auth test`
 
@@ -175,7 +175,7 @@ EXAMPLES
   $ pg psql auth test -p prod
 ```
 
-_See code: [src/commands/psql/auth/test.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/auth/test.ts)_
+_See code: [src/commands/psql/auth/test.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/auth/test.ts)_
 
 ## `pg psql auth update`
 
@@ -207,7 +207,7 @@ EXAMPLES
   $ pg psql auth update -p test
 ```
 
-_See code: [src/commands/psql/auth/update.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/auth/update.ts)_
+_See code: [src/commands/psql/auth/update.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/auth/update.ts)_
 
 ## `pg psql databases`
 
@@ -215,10 +215,13 @@ List all databases accessible on the PostgreSQL server
 
 ```
 USAGE
-  $ pg psql databases [--profile <value>]
+  $ pg psql databases [--json] [-p <value>]
 
 FLAGS
-  --profile=<value>  Database profile name from config
+  -p, --profile=<value>  Database profile name from config
+
+GLOBAL FLAGS
+  --json  Format output as json.
 
 DESCRIPTION
   List all databases accessible on the PostgreSQL server
@@ -226,10 +229,10 @@ DESCRIPTION
 EXAMPLES
   $ pg psql databases
 
-  $ pg psql databases --profile staging
+  $ pg psql databases -p staging
 ```
 
-_See code: [src/commands/psql/databases.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/databases.ts)_
+_See code: [src/commands/psql/databases.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/databases.ts)_
 
 ## `pg psql describe-table TABLE`
 
@@ -237,15 +240,18 @@ Describe the structure of a PostgreSQL table
 
 ```
 USAGE
-  $ pg psql describe-table TABLE [--format table|json|toon] [--profile <value>]
+  $ pg psql describe-table TABLE [--json] [--format table|json|toon] [-p <value>]
 
 ARGUMENTS
   TABLE  Table name to describe
 
 FLAGS
-  --format=<option>  [default: table] Output format
-                     <options: table|json|toon>
-  --profile=<value>  Database profile name from config
+  -p, --profile=<value>  Database profile name from config
+      --format=<option>  [default: table] Output format
+                         <options: table|json|toon>
+
+GLOBAL FLAGS
+  --json  Format output as json.
 
 DESCRIPTION
   Describe the structure of a PostgreSQL table
@@ -253,10 +259,10 @@ DESCRIPTION
 EXAMPLES
   $ pg psql describe-table users
 
-  $ pg psql describe-table orders --format json --profile prod
+  $ pg psql describe-table orders --format json -p prod
 ```
 
-_See code: [src/commands/psql/describe-table.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/describe-table.ts)_
+_See code: [src/commands/psql/describe-table.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/describe-table.ts)_
 
 ## `pg psql explain-query QUERY`
 
@@ -264,15 +270,18 @@ Show the execution plan for a PostgreSQL query
 
 ```
 USAGE
-  $ pg psql explain-query QUERY [--format table|json|toon] [--profile <value>]
+  $ pg psql explain-query QUERY [--json] [--format table|json|toon] [-p <value>]
 
 ARGUMENTS
   QUERY  SQL query to explain
 
 FLAGS
-  --format=<option>  [default: table] Output format
-                     <options: table|json|toon>
-  --profile=<value>  Database profile name from config
+  -p, --profile=<value>  Database profile name from config
+      --format=<option>  [default: table] Output format
+                         <options: table|json|toon>
+
+GLOBAL FLAGS
+  --json  Format output as json.
 
 DESCRIPTION
   Show the execution plan for a PostgreSQL query
@@ -283,7 +292,7 @@ EXAMPLES
   $ pg psql explain-query "SELECT * FROM orders JOIN users ON orders.user_id = users.id" --format json
 ```
 
-_See code: [src/commands/psql/explain-query.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/explain-query.ts)_
+_See code: [src/commands/psql/explain-query.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/explain-query.ts)_
 
 ## `pg psql indexes TABLE`
 
@@ -291,15 +300,18 @@ Show indexes for a PostgreSQL table
 
 ```
 USAGE
-  $ pg psql indexes TABLE [--format table|json|toon] [--profile <value>]
+  $ pg psql indexes TABLE [--json] [--format table|json|toon] [-p <value>]
 
 ARGUMENTS
   TABLE  Table name to show indexes for
 
 FLAGS
-  --format=<option>  [default: table] Output format
-                     <options: table|json|toon>
-  --profile=<value>  Database profile name from config
+  -p, --profile=<value>  Database profile name from config
+      --format=<option>  [default: table] Output format
+                         <options: table|json|toon>
+
+GLOBAL FLAGS
+  --json  Format output as json.
 
 DESCRIPTION
   Show indexes for a PostgreSQL table
@@ -307,10 +319,10 @@ DESCRIPTION
 EXAMPLES
   $ pg psql indexes users
 
-  $ pg psql indexes orders --format json --profile prod
+  $ pg psql indexes orders --format json -p prod
 ```
 
-_See code: [src/commands/psql/indexes.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/indexes.ts)_
+_See code: [src/commands/psql/indexes.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/indexes.ts)_
 
 ## `pg psql query QUERY`
 
@@ -318,16 +330,19 @@ Execute a SQL query against a PostgreSQL database
 
 ```
 USAGE
-  $ pg psql query QUERY [--format table|json|csv|toon] [--profile <value>] [--skip-confirmation]
+  $ pg psql query QUERY [--json] [--format table|json|csv|toon] [-p <value>] [--skip-confirmation]
 
 ARGUMENTS
   QUERY  SQL query to execute
 
 FLAGS
-  --format=<option>    [default: table] Output format
-                       <options: table|json|csv|toon>
-  --profile=<value>    Database profile name from config
-  --skip-confirmation  Skip confirmation prompt for destructive operations
+  -p, --profile=<value>    Database profile name from config
+      --format=<option>    [default: table] Output format
+                           <options: table|json|csv|toon>
+      --skip-confirmation  Skip confirmation prompt for destructive operations
+
+GLOBAL FLAGS
+  --json  Format output as json.
 
 DESCRIPTION
   Execute a SQL query against a PostgreSQL database
@@ -337,10 +352,10 @@ EXAMPLES
 
   $ pg psql query "UPDATE users SET email = 'user@email.com' WHERE id = 999" --format json
 
-  $ pg psql query "DELETE FROM sessions" --profile prod --skip-confirmation
+  $ pg psql query "DELETE FROM sessions" -p prod --skip-confirmation
 ```
 
-_See code: [src/commands/psql/query.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/query.ts)_
+_See code: [src/commands/psql/query.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/query.ts)_
 
 ## `pg psql tables`
 
@@ -348,10 +363,13 @@ List all tables in the current PostgreSQL database
 
 ```
 USAGE
-  $ pg psql tables [--profile <value>]
+  $ pg psql tables [--json] [-p <value>]
 
 FLAGS
-  --profile=<value>  Database profile name from config
+  -p, --profile=<value>  Database profile name from config
+
+GLOBAL FLAGS
+  --json  Format output as json.
 
 DESCRIPTION
   List all tables in the current PostgreSQL database
@@ -359,8 +377,8 @@ DESCRIPTION
 EXAMPLES
   $ pg psql tables
 
-  $ pg psql tables --profile local
+  $ pg psql tables -p local
 ```
 
-_See code: [src/commands/psql/tables.ts](https://github.com/hesedcasa/psql/blob/v0.4.1/src/commands/psql/tables.ts)_
+_See code: [src/commands/psql/tables.ts](https://github.com/hesedcasa/psql/blob/v0.5.1/src/commands/psql/tables.ts)_
 <!-- commandsstop -->

package/dist/base-command.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export declare abstract class BaseCommand extends Command {
+    static enableJsonFlag: boolean;
+    jsonEnabled(): boolean;
+    protected parse(options?: any, argv?: string[]): Promise<any>;
+    protected parseJsonOutput(output?: string): unknown;
+    protected toErrorJson(err: unknown): {
+        error: string;
+    };
+    private formatFlagValue;
+    private hasFormatFlag;
+}

package/dist/base-command.js

@@ -0,0 +1,50 @@
+import { Command } from '@oclif/core';
+export class BaseCommand extends Command {
+    static enableJsonFlag = true;
+    jsonEnabled() {
+        const separatorIndex = this.argv.indexOf('--');
+        const flagArgs = separatorIndex === -1 ? this.argv : this.argv.slice(0, separatorIndex);
+        if (this.hasFormatFlag(flagArgs))
+            return this.formatFlagValue(flagArgs) === 'json';
+        return flagArgs.includes('--json');
+    }
+    // oclif sets this.parsed=true only after Parser.parse() returns successfully.
+    // When parse() throws (e.g. missing required arg), this.parsed stays false and
+    // _run() emits an UnparsedCommand warning. The finally block prevents that.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async parse(options, argv) {
+        try {
+            return await super.parse(options, argv);
+        }
+        finally {
+            this.parsed = true;
+        }
+    }
+    parseJsonOutput(output) {
+        if (!output)
+            return null;
+        try {
+            return JSON.parse(output);
+        }
+        catch {
+            return output;
+        }
+    }
+    // oclif's default toErrorJson returns the raw error object which for
+    // CLIParseError includes context:this (the full config). Strip it down.
+    toErrorJson(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: message };
+    }
+    formatFlagValue(flagArgs) {
+        for (const [index, arg] of flagArgs.entries()) {
+            if (arg === '--format')
+                return flagArgs[index + 1];
+            if (arg.startsWith('--format='))
+                return arg.slice('--format='.length);
+        }
+    }
+    hasFormatFlag(flagArgs) {
+        return flagArgs.some((arg) => arg === '--format' || arg.startsWith('--format='));
+    }
+}

package/dist/commands/psql/databases.d.ts

@@ -1,9 +1,11 @@
 import { Command } from '@oclif/core';
 export default class PostgresDatabases extends Command {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    jsonEnabled(): boolean;
+    run(): Promise<string[]>;
 }

package/dist/commands/psql/databases.js

@@ -2,22 +2,21 @@ import { Command, Flags } from '@oclif/core';
 import { closeConnections, listDatabases } from '../../psql/index.js';
 export default class PostgresDatabases extends Command {
     static description = 'List all databases accessible on the PostgreSQL server';
-    static examples = [
-        '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> --profile staging',
-    ];
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %>', '<%= config.bin %> <%= command.id %> -p staging'];
     static flags = {
-        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
     };
+    jsonEnabled() {
+        return true;
+    }
     async run() {
         const { flags } = await this.parse(PostgresDatabases);
         const result = await listDatabases(this.config, flags.profile);
         await closeConnections();
         if (result.success) {
-            this.logJson(result.databases);
-        }
-        else {
-            this.error(result.error ?? 'Failed to list databases');
+            return result.databases ?? [];
         }
+        this.error(result.error ?? 'Failed to list databases');
     }
 }

package/dist/commands/psql/describe-table.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
-export default class PostgresDescribeTable extends Command {
+import { BaseCommand } from '../../base-command.js';
+export default class PostgresDescribeTable extends BaseCommand {
     static args: {
         table: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -9,5 +9,5 @@ export default class PostgresDescribeTable extends Command {
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    run(): Promise<unknown>;
 }

package/dist/commands/psql/describe-table.js

@@ -1,13 +1,14 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
 import { closeConnections, describeTable } from '../../psql/index.js';
-export default class PostgresDescribeTable extends Command {
+export default class PostgresDescribeTable extends BaseCommand {
     static args = {
         table: Args.string({ description: 'Table name to describe', required: true }),
     };
     static description = 'Describe the structure of a PostgreSQL table';
     static examples = [
         '<%= config.bin %> <%= command.id %> users',
-        '<%= config.bin %> <%= command.id %> orders --format json --profile prod',
+        '<%= config.bin %> <%= command.id %> orders --format json -p prod',
     ];
     static flags = {
         format: Flags.string({
@@ -15,7 +16,7 @@ export default class PostgresDescribeTable extends Command {
             description: 'Output format',
             options: ['table', 'json', 'toon'],
         }),
-        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
     };
     async run() {
         const { args, flags } = await this.parse(PostgresDescribeTable);
@@ -23,9 +24,8 @@ export default class PostgresDescribeTable extends Command {
         await closeConnections();
         if (result.success) {
             this.log(result.result ?? '');
+            return result;
         }
-        else {
-            this.error(result.error ?? 'Failed to describe table');
-        }
+        this.error(result.error ?? 'Failed to describe table');
     }
 }

package/dist/commands/psql/explain-query.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
-export default class PostgresExplain extends Command {
+import { BaseCommand } from '../../base-command.js';
+export default class PostgresExplain extends BaseCommand {
     static args: {
         query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -9,5 +9,5 @@ export default class PostgresExplain extends Command {
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    run(): Promise<unknown>;
 }

package/dist/commands/psql/explain-query.js

@@ -1,6 +1,7 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
 import { closeConnections, explainQuery } from '../../psql/index.js';
-export default class PostgresExplain extends Command {
+export default class PostgresExplain extends BaseCommand {
     static args = {
         query: Args.string({ description: 'SQL query to explain', required: true }),
     };
@@ -15,7 +16,7 @@ export default class PostgresExplain extends Command {
             description: 'Output format',
             options: ['table', 'json', 'toon'],
         }),
-        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
     };
     async run() {
         const { args, flags } = await this.parse(PostgresExplain);
@@ -23,9 +24,8 @@ export default class PostgresExplain extends Command {
         await closeConnections();
         if (result.success) {
             this.log(result.result ?? '');
+            return result;
         }
-        else {
-            this.error(result.error ?? 'Failed to explain query');
-        }
+        this.error(result.error ?? 'Failed to explain query');
     }
 }

package/dist/commands/psql/indexes.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
-export default class PostgresIndexes extends Command {
+import { BaseCommand } from '../../base-command.js';
+export default class PostgresIndexes extends BaseCommand {
     static args: {
         table: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -9,5 +9,5 @@ export default class PostgresIndexes extends Command {
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    run(): Promise<unknown>;
 }

package/dist/commands/psql/indexes.js

@@ -1,13 +1,14 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
 import { closeConnections, showIndexes } from '../../psql/index.js';
-export default class PostgresIndexes extends Command {
+export default class PostgresIndexes extends BaseCommand {
     static args = {
         table: Args.string({ description: 'Table name to show indexes for', required: true }),
     };
     static description = 'Show indexes for a PostgreSQL table';
     static examples = [
         '<%= config.bin %> <%= command.id %> users',
-        '<%= config.bin %> <%= command.id %> orders --format json --profile prod',
+        '<%= config.bin %> <%= command.id %> orders --format json -p prod',
     ];
     static flags = {
         format: Flags.string({
@@ -15,7 +16,7 @@ export default class PostgresIndexes extends Command {
             description: 'Output format',
             options: ['table', 'json', 'toon'],
         }),
-        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
     };
     async run() {
         const { args, flags } = await this.parse(PostgresIndexes);
@@ -23,9 +24,8 @@ export default class PostgresIndexes extends Command {
         await closeConnections();
         if (result.success) {
             this.log(result.result ?? '');
+            return result;
         }
-        else {
-            this.error(result.error ?? 'Failed to show indexes');
-        }
+        this.error(result.error ?? 'Failed to show indexes');
     }
 }

package/dist/commands/psql/query.d.ts

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
-export default class PostgresQuery extends Command {
+import { BaseCommand } from '../../base-command.js';
+export default class PostgresQuery extends BaseCommand {
     static args: {
         query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -10,5 +10,5 @@ export default class PostgresQuery extends Command {
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'skip-confirmation': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
-    run(): Promise<void>;
+    run(): Promise<unknown>;
 }

package/dist/commands/psql/query.js

@@ -1,6 +1,7 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
 import { closeConnections, executeQuery } from '../../psql/index.js';
-export default class PostgresQuery extends Command {
+export default class PostgresQuery extends BaseCommand {
     static args = {
         query: Args.string({ description: 'SQL query to execute', required: true }),
     };
@@ -8,7 +9,7 @@ export default class PostgresQuery extends Command {
     static examples = [
         '<%= config.bin %> <%= command.id %> "SELECT * FROM users LIMIT 10"',
         '<%= config.bin %> <%= command.id %> "UPDATE users SET email = \'user@email.com\' WHERE id = 999" --format json',
-        '<%= config.bin %> <%= command.id %> "DELETE FROM sessions" --profile prod --skip-confirmation',
+        '<%= config.bin %> <%= command.id %> "DELETE FROM sessions" -p prod --skip-confirmation',
     ];
     static flags = {
         format: Flags.string({
@@ -16,7 +17,7 @@ export default class PostgresQuery extends Command {
             description: 'Output format',
             options: ['table', 'json', 'csv', 'toon'],
         }),
-        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
         'skip-confirmation': Flags.boolean({
             default: false,
             description: 'Skip confirmation prompt for destructive operations',
@@ -27,13 +28,19 @@ export default class PostgresQuery extends Command {
         const result = await executeQuery(this.config, args.query, flags.profile, flags.format, flags['skip-confirmation']);
         await closeConnections();
         if (result.success) {
+            // Notices (warnings, row counts) go to stderr so machine-readable formats
+            // leave stdout as clean, parseable data.
+            if (result.notices)
+                this.logToStderr(result.notices);
+            if (this.jsonEnabled())
+                return this.parseJsonOutput(result.result);
             this.log(result.result ?? '');
+            return result;
         }
-        else if (result.requiresConfirmation) {
+        if (result.requiresConfirmation) {
             this.log(`${result.message ?? 'Destructive operation requires confirmation.'}\nRe-run with --skip-confirmation to proceed.`);
+            return result;
         }
-        else {
-            this.error(result.error ?? 'Query failed');
-        }
+        this.error(result.error ?? 'Query failed');
     }
 }

package/dist/commands/psql/tables.d.ts

@@ -1,9 +1,11 @@
 import { Command } from '@oclif/core';
 export default class PostgresTables extends Command {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    jsonEnabled(): boolean;
+    run(): Promise<string[]>;
 }

package/dist/commands/psql/tables.js

@@ -2,22 +2,21 @@ import { Command, Flags } from '@oclif/core';
 import { closeConnections, listTables } from '../../psql/index.js';
 export default class PostgresTables extends Command {
     static description = 'List all tables in the current PostgreSQL database';
-    static examples = [
-        '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> --profile local',
-    ];
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> <%= command.id %>', '<%= config.bin %> <%= command.id %> -p local'];
     static flags = {
-        profile: Flags.string({ description: 'Database profile name from config', required: false }),
+        profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
     };
+    jsonEnabled() {
+        return true;
+    }
     async run() {
         const { flags } = await this.parse(PostgresTables);
         const result = await listTables(this.config, flags.profile);
         await closeConnections();
         if (result.success) {
-            this.logJson(result.tables);
-        }
-        else {
-            this.error(result.error ?? 'Failed to list tables');
+            return result.tables ?? [];
         }
+        this.error(result.error ?? 'Failed to list tables');
     }
 }

package/dist/psql/database.d.ts

@@ -8,6 +8,7 @@
 export interface QueryResult {
     error?: string;
     message?: string;
+    notices?: string;
     requiresConfirmation?: boolean;
     result?: string;
     success: boolean;

package/dist/psql/index.d.ts

@@ -1,2 +1 @@
-export type { ConnectionTestResult } from './database.js';
 export { closeConnections, describeTable, executeQuery, explainQuery, listDatabases, listTables, showIndexes, testDirectConnection, } from './postgres-client.js';

package/dist/psql/postgres-utils.d.ts

@@ -12,7 +12,8 @@ export declare class PostgreSQLUtil implements DatabaseUtil {
     listTables(profileName: string): Promise<TableListResult>;
     showIndexes(profileName: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<IndexResult>;
     testConnection(profileName: string): Promise<ConnectionTestResult>;
+    private formatReadResult;
     private formatRows;
-    private formatSelectResult;
+    private formatWriteResult;
     private getConnection;
 }

package/dist/psql/postgres-utils.js

@@ -50,36 +50,36 @@ export class PostgreSQLUtil {
                 };
             }
         }
+        // Machine-readable formats must emit only the data payload on stdout, so
+        // analysis warnings and status lines are collected as notices instead.
+        const machineFormat = format === 'json' || format === 'csv' || format === 'toon';
+        const notices = [];
         const warnings = analyzeQuery(query);
-        let warningText = '';
         if (warnings.length > 0) {
-            warningText =
-                'Query Analysis:\n' +
-                    warnings.map((w) => `  [${w.level.toUpperCase()}] ${w.message}\n  → ${w.suggestion}`).join('\n') +
-                    '\n\n';
+            notices.push('Query Analysis:\n' +
+                warnings.map((w) => `  [${w.level.toUpperCase()}] ${w.message}\n  → ${w.suggestion}`).join('\n'));
         }
         let finalQuery = query;
         const queryType = getQueryType(query);
         if (queryType === 'SELECT') {
             finalQuery = applyDefaultLimit(query, this.config.safety.defaultLimit);
             if (finalQuery !== query) {
-                warningText += `Applied default LIMIT ${this.config.safety.defaultLimit}\n\n`;
+                notices.push(`Applied default LIMIT ${this.config.safety.defaultLimit}`);
             }
         }
         try {
             const client = await this.getConnection(profileName);
             const result = await client.query(finalQuery);
-            let output = '';
-            if (result.rows.length > 0 || result.command === 'SELECT' || result.command === 'EXPLAIN') {
-                output += this.formatSelectResult(result.rows, result.fields, format);
-            }
-            else {
-                const affectedRows = result.rowCount ?? 0;
-                output += `Query executed successfully.\n`;
-                output += `Affected rows: ${affectedRows}\n`;
-            }
+            const isRead = result.rows.length > 0 || result.command === 'SELECT' || result.command === 'EXPLAIN';
+            const data = isRead
+                ? this.formatReadResult(result.rows, result.fields, format, notices)
+                : this.formatWriteResult(result.rowCount ?? 0, notices);
+            const notice = notices.join('\n\n');
+            // For human (table) output everything stays on stdout, exactly as before.
+            // For machine formats the data is returned alone and notices go to stderr.
             return {
-                result: warningText + output,
+                notices: machineFormat ? notice : undefined,
+                result: machineFormat ? data : `${notice}\n\n${data}`,
                 success: true,
             };
         }
@@ -185,12 +185,17 @@ export class PostgreSQLUtil {
             };
         }
     }
+    formatReadResult(rows, fields, format, notices) {
+        const rowCount = Array.isArray(rows) ? rows.length : 0;
+        notices.push(`Query executed successfully. Rows returned: ${rowCount}`);
+        return this.formatRows(rows, fields, format);
+    }
     formatRows(rows, fields, format) {
         return FORMATTERS[format](rows, fields);
     }
-    formatSelectResult(rows, fields, format) {
-        const rowCount = Array.isArray(rows) ? rows.length : 0;
-        return `Query executed successfully. Rows returned: ${rowCount}\n\n` + this.formatRows(rows, fields, format);
+    formatWriteResult(affectedRows, notices) {
+        notices.push('Query executed successfully.');
+        return `Affected rows: ${affectedRows}\n`;
     }
     async getConnection(profileName) {
         const existing = this.connections.get(profileName);

package/oclif.manifest.json

@@ -6,10 +6,18 @@
       "description": "List all databases accessible on the PostgreSQL server",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
-        "<%= config.bin %> <%= command.id %> --profile staging"
+        "<%= config.bin %> <%= command.id %> -p staging"
       ],
       "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "profile": {
+          "char": "p",
           "description": "Database profile name from config",
           "name": "profile",
           "required": false,
@@ -25,7 +33,7 @@
       "pluginName": "@hesed/psql",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
+      "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -46,9 +54,16 @@
       "description": "Describe the structure of a PostgreSQL table",
       "examples": [
         "<%= config.bin %> <%= command.id %> users",
-        "<%= config.bin %> <%= command.id %> orders --format json --profile prod"
+        "<%= config.bin %> <%= command.id %> orders --format json -p prod"
       ],
       "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "format": {
           "description": "Output format",
           "name": "format",
@@ -63,6 +78,7 @@
           "type": "option"
         },
         "profile": {
+          "char": "p",
           "description": "Database profile name from config",
           "name": "profile",
           "required": false,
@@ -78,7 +94,7 @@
       "pluginName": "@hesed/psql",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
+      "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -102,6 +118,13 @@
         "<%= config.bin %> <%= command.id %> \"SELECT * FROM orders JOIN users ON orders.user_id = users.id\" --format json"
       ],
       "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "format": {
           "description": "Output format",
           "name": "format",
@@ -116,6 +139,7 @@
           "type": "option"
         },
         "profile": {
+          "char": "p",
           "description": "Database profile name from config",
           "name": "profile",
           "required": false,
@@ -131,7 +155,7 @@
       "pluginName": "@hesed/psql",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
+      "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -152,9 +176,16 @@
       "description": "Show indexes for a PostgreSQL table",
       "examples": [
         "<%= config.bin %> <%= command.id %> users",
-        "<%= config.bin %> <%= command.id %> orders --format json --profile prod"
+        "<%= config.bin %> <%= command.id %> orders --format json -p prod"
       ],
       "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "format": {
           "description": "Output format",
           "name": "format",
@@ -169,6 +200,7 @@
           "type": "option"
         },
         "profile": {
+          "char": "p",
           "description": "Database profile name from config",
           "name": "profile",
           "required": false,
@@ -184,7 +216,7 @@
       "pluginName": "@hesed/psql",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
+      "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -206,9 +238,16 @@
       "examples": [
         "<%= config.bin %> <%= command.id %> \"SELECT * FROM users LIMIT 10\"",
         "<%= config.bin %> <%= command.id %> \"UPDATE users SET email = 'user@email.com' WHERE id = 999\" --format json",
-        "<%= config.bin %> <%= command.id %> \"DELETE FROM sessions\" --profile prod --skip-confirmation"
+        "<%= config.bin %> <%= command.id %> \"DELETE FROM sessions\" -p prod --skip-confirmation"
       ],
       "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "format": {
           "description": "Output format",
           "name": "format",
@@ -224,6 +263,7 @@
           "type": "option"
         },
         "profile": {
+          "char": "p",
           "description": "Database profile name from config",
           "name": "profile",
           "required": false,
@@ -245,7 +285,7 @@
       "pluginName": "@hesed/psql",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
+      "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -260,10 +300,18 @@
       "description": "List all tables in the current PostgreSQL database",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
-        "<%= config.bin %> <%= command.id %> --profile local"
+        "<%= config.bin %> <%= command.id %> -p local"
       ],
       "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "profile": {
+          "char": "p",
           "description": "Database profile name from config",
           "name": "profile",
           "required": false,
@@ -279,7 +327,7 @@
       "pluginName": "@hesed/psql",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
+      "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -634,5 +682,5 @@
       ]
     }
   },
-  "version": "0.4.1"
+  "version": "0.5.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hesed/psql",
   "description": "CLI for PostgreSQL database interaction",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "author": "Hesed",
   "bin": {
     "pg": "./bin/run.js"