Quickstart

Remember it

monkeys remember SUPER_SECRET

Type sesame at the prompt.

Run with monkeys

monkeys run SUPER_SECRET sh -c '
  test "$SUPER_SECRET" = sesame && echo opened || echo closed
  echo "the word was $SUPER_SECRET"
'

opened
the word was [redacted SUPER_SECRET]

The right word reached the command, and what the command printed came back with the secret taken out. run becomes the command once the secret is set, so the exit status, the output and the signals are the command's own.

Run without monkeys

sh -c 'test "$SUPER_SECRET" = sesame && echo opened || echo closed'

closed

Forget and retry

monkeys forget SUPER_SECRET
monkeys run SUPER_SECRET sh -c '
  test "$SUPER_SECRET" = sesame && echo opened || echo closed
'

forgot SUPER_SECRET
monkeys: SUPER_SECRET is not remembered yet
nothing happened. a human types the secret into:
  monkeys remember SUPER_SECRET
then try again.

Nothing ran at all: a missing secret stops run before the command starts, and the message says what to do, which is what an agent passes on.

Inside a git checkout the first step also started a .monkeys and listed SUPER_SECRET in it, since that file is how a project says which keys it needs. monkeys drop SUPER_SECRET takes the key back out of it, and monkeys poo writes a .env of those keys with nothing after them, for a tool that wants the file to exist.