quicproquo/playbooks

quicprochat Playbooks

YAML-based scripted command sequences for the qpc client.

Running a playbook

# Build with playbook support
cargo build -p quicprochat-client --features playbook

# Run a playbook
cargo run -p quicprochat-client --features playbook -- \
  run playbooks/smoke-test.yaml \
  --server 127.0.0.1:7000 \
  --username alice --password hunter2 \
  --danger-accept-invalid-certs

# Override variables
cargo run -p quicprochat-client --features playbook -- \
  run playbooks/smoke-test.yaml \
  -V recipient=charlie -V server=remote.example.com:7000

YAML format

name: "My playbook"
description: "Optional description"
variables:
  key: "value"              # available as $key in args
steps:
  - command: dm              # any slash command name (without /)
    args:
      username: "$key"       # variable substitution
  - command: send
    args:
      text: "Hello!"
  - command: assert
    condition: message_count # connected, logged_in, in_conversation, message_count, member_count
    op: gte                  # eq, ne, gt, lt, gte, lte (or ==, !=, >, <, >=, <=)
    value: 1

Variable substitution

• $varname — replaced with the variable value
• ${VAR:-default} — replaced with VAR, falling back to env var, then default
• Variables from --var KEY=VALUE override playbook defaults
• _server and _username are auto-injected

Step options

Field	Type	Description
command	string	Command name (required)
args	map	Command arguments
condition	string	For assert steps
op	string	Comparison operator for asserts
value	any	Expected value for asserts
capture	string	Store output in this variable
on_error	string	fail (default), skip, continue
loop	object	Repeat with {var, from, to}

Loop syntax

  - command: send
    args:
      text: "Message $i"
    loop:
      var: i
      from: 1
      to: 10

Available commands

All REPL slash commands (without the /): help, quit, whoami, list, switch, dm, create-group, invite, remove, leave, join, members, group-info, rename, history, verify, update-key, typing, react, edit, delete, send-file, download, delete-account, disappear, privacy, verify-fs, rotate-all-keys, devices, register-device, revoke-device, mesh-peers, mesh-send, mesh-broadcast, mesh-subscribe, mesh-route, mesh-identity, mesh-store.

Plus lifecycle commands: send (send a chat message), wait (pause), assert (check condition), set-var (set variable).

Programmatic Rust API

use quicprochat_client::{PlaybookRunner, Command, CommandRegistry, CommandResult};

// From YAML file
let mut runner = PlaybookRunner::from_file(Path::new("playbook.yaml"))?;
runner.set_var("recipient", "bob");
let report = runner.run(&mut session, &client).await;
println!("{report}");

// Single command execution
let cmd = Command::Dm { username: "alice".into() };
let result = CommandRegistry::execute(&cmd, &mut session, &client).await;
assert!(result.success);

Example playbooks

File	Description
health-check.yaml	Verify server connectivity
smoke-test.yaml	Quick E2E: DM + send + history
register-and-dm.yaml	DM exchange between two users
group-lifecycle.yaml	Create/invite/send/leave group
stress-send.yaml	Send 100 messages in a loop