Struct AfdCli 

pub struct AfdCli { /* private fields */ }

afpsql gives agents a reliable PostgreSQL contract: structured stdout events, first-class SSH/container transports, explicit write permissions, stable pipe sessions, and machine-readable failures.

Interface Policy

• default mode is canonical agent-first CLI
• --mode psql is argument translation only; runtime output stays JSONL
• stdout carries protocol events; stderr is not a protocol channel
• native CLI and pipe mode default to read-only transactions; writes require permission
• SSH/container transports keep afpsql local instead of running human psql across boundaries

Modes

• default (native CLI): one SQL action per process — a single agent step
• --mode pipe: a long-lived JSONL session with id correlation and named sessions for multi-step work
• --mode psql: run existing psql scripts unchanged — flags are translated, runtime output stays JSONL

Query Sources and Parameters

• use --sql for inline SQL or --sql-file for a file
• use repeatable --param N=value for positional binds
• placeholder count is validated from prepared-statement metadata, not by SQL text scanning

Connection Sources

• --dsn-secret for a PostgreSQL URI
• --conninfo-secret for libpq-style conninfo
• or discrete --host, --port, --user, --dbname, --password-secret
• every *-secret flag has a *-secret-env partner that reads the value from a named environment variable
• every secret slot also has a *-secret-config FILE DOT_PATH source for JSON, TOML, YAML, or dotenv
• add --ssh user@server when PostgreSQL is reachable only from the server boundary
• add --container TARGET when PostgreSQL is reachable only from inside a container boundary
• use named container scope flags instead of raw driver option passthrough
• use --container-driver docker|podman|nerdctl|compose|kubectl for the exec syntax
• combine --ssh user@server --container TARGET for containers on an SSH host
• agent-first environment fallbacks: AFPSQL_*
• PostgreSQL environment fallbacks: PGHOST, PGPORT, PGUSER, PGDATABASE, PGPASSWORD, PGSSLMODE

Result Shaping

• default mode buffers a bounded inline result
• use --stream-rows for large result sets, with --batch-rows and --batch-bytes to tune chunk size
• --output json|yaml|plain changes rendering only, not the runtime schema

Examples

afpsql --sql "select now() as now_rfc3339"
afpsql --sql-file ./query.sql
afpsql --sql 'select * from users where id = $1' --param 1=123
afpsql --dsn-secret-env DATABASE_URL --sql "select 1"
afpsql --dsn-secret-config config.yaml database.url --sql "select 1"
afpsql --ssh user@server --host 127.0.0.1 --port 5432 --user app --dbname appdb --sql "select 1"
afpsql --container pg-container --dsn-secret-env DATABASE_URL --sql "select 1"
afpsql --ssh root@server --container app --host host.container.internal --port 5432 --user app --dbname appdb --sql "select 1"
afpsql --mode psql -h 127.0.0.1 -p 5432 -U app -d appdb -c "select 1"
afpsql --sql "select * from big_table" --stream-rows --batch-rows 1000
afpsql --mode pipe
afpsql psql status
afpsql psql install
afpsql skill status
afpsql skill install

Exit Codes

• 0: query completed successfully
• 1: SQL error or runtime error
• 2: invalid CLI arguments

Trait Implementations

impl Args for AfdCli

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl CommandFactory for AfdCli

fn command<'b>() -> Command

Build a Command that can instantiate Self.

fn command_for_update<'b>() -> Command

Build a Command that can update self.

impl FromArgMatches for AfdCli

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Parser for AfdCli

fn parse() -> Self

Parse from std::env::args_os(), exit on error.

fn try_parse() -> Result<Self, Error>

Parse from std::env::args_os(), return Err on error.

fn parse_from<I, T>(itr: I) -> Self

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error.

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error.

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, return Err on error.