Secret Agent

Filling Out Forms on macOS and Windows

Secret Agent is a helper application which runs along side Codebook on macOS and Windows. It allows you to quickly access and insert your Codebook data into other applications and browsers using a global keyboard shortcut, without bringing up the main Codebook window. Secret Agent is not available on iOS and Android.

There are 3 different features of Secret Agent:

Insert a single value using Secret Agent
Run Default Action – enters username/email and password
Custom Secret Agent Action – you define the fields and commands to be run

Enabling The Feature

macOS: Codebook -> Settings -> General -> "Enable Secret Agent"
Windows: File -> Preferences -> "Run Secret Agent at Windows Login"

Enabling The Feature

Adjust the Secret Agent Keybinding to your liking, or just leave it as the default.

Default hotkey combinations:

macOS: ⇧ + ⌘ + \
Windows: ⇧ + Ctrl + \

1. Insert a single value using Secret Agent

The simplest means of copying a password into another app is to activate the Secret Agent window, look up the password you need, and insert it into the active text field.

Place your cursor in the field which you'd like to fill (i.e. password field of a login screen)
Launch Secret Agent using the global keyboard shortcut you specified in Preferences or Settings
(for macOS: ⇧ + ⌘ + \ for Windows: ⇧ + Ctrl + \)
Search for the desired entry
Select the entry and the desired field, then and press enter – the field will be inserted

2. Run Default Action

Run Default Action uses fields from Codebook to populate fields on a form. You access Secret Agent the same way, using the hotkeys. Select the desired Codebook Entry and then press the Play button (or ⌘ + r in macOS and Ctrl + r in Windows). The username/email and password fields will be inserted followed by enter/submit in the active application. (To enter a single field value, you press the enter key – see above.) It attempts to run a default action using the username/email and password fields from the entry and inserting them into the active application.

Note: Codebook first looks to see if you have a Secret Agent Action field on the entry (see below). If you do, that will be run instead.

With your cursor in the email/username on the login screen of an application, launch Secret Agent using the hotkey you specified in Settings (for macOS: ⇧ + ⌘ + \ for Windows: ⇧ + Ctrl + \)
Search for the desired entry
Select the entry then and press the Play button – the username/email and password fields will be inserted followed by the enter/submit

3. Custom Secret Agent Action

Custom Secret Agent Action allows you to perform one action to insert multiple data values. You can customized which fields in an Entry will be inserted into the active application. To make this feature more useful, you can also include commands between data values (tab, enter, space and wait). This is demonstrated in the sample video below whichs allows enters values into a two screen login process.

In this example, we're logging into Dropbox with 2 factor authentication enabled. The custom Secret Agent Action is: #[email]<tab>#[password]<enter><wait3>#[totp]<enter>. It's associated with this Secret Agent Action suggestion: Page 1: Email & Password, Page2: TOTP (See Helpful Tips and Suggestions for more information.)

Setting up a Custom Action

Creating your own Secret Agent Action involves two steps:

Add a custom label of type "Secret Agent Action"
Add a field of the custom label to an Entry

1. Add a custom label of type "Secret Agent Action"

Custom Secret Agent actions must be setup/defined in a field with Mode of Secret Agent Action.
File -> Customize Labels. Add a new label, name it whatever you'd like (e.g. "Quick Fill"), and set the 'Mode' to "Secret Agent Action".
Note: new installations should have a "Secret Agent Action" field already installed by default.

Add a custom label of type 'Secret Agent Action'

2. Add a field of the name you just created ("Quick Fill")

Open an existing entry or create a new entry. Add a field, and set the label to the "Quick Fill" label you just created. Start typing in the field, you'll notice a list of suggestions shows up in a small table underneath. You can arrow down or up (or click) to cycle through the suggestions to see what their representative commands are. Once you find one that you'll think will be suitable for the site or form you're trying to fill, hit enter, and save the entry.

Quick Fill

Try it out!

Go to a website or form that you'd like to fill in, click in the first field that you'd like to fill and call Secret Agent using it's defined key combination. Search for the appropriate entry (in our example "New Entry") and arrow down to the Secret Agent Action field ("Quick Fill" in our example), hit enter (or ⌘ + r in macOS and Ctrl + r in Windows or the Play button ) and the command sequence will be activated. In our example, it will fill the username ("MyUsername"), tab, fill the password ("@=wX[7qp,rceZ7"dH"), and hit enter to sign in.

Example Sign In

Additional Triggering Option

You can also enter the Secret Agent hotkey (⌘ + r in macOS and Ctrl + r in Windows) to run the Default Action/Custom Action when you have selected the desired search result (without selecting into the details of the entry). In the example below, pressing the run hot key combination with Zetetic Discuss Forum selected in the Codebook Secret Agent search results window will cause the email and password fields in the entry to populated followed by enter thereby logging you into the Discuss Forum.

Example use of Hot Key from Search results

Helpful tips and suggestions

We recommend filling the target form once manually (without using the mouse) to determine what commands are necessary. As you're filling it, note which keys you're using to navigate between fields and submit the form. This should directly parallel with the available commands: <tab>, <enter>, <waitN> (where N is the number of seconds to wait) <space> (we've found this one handy for toggling those "Remember me" check boxes).

We've pre-populated the Secret Agent Action suggestions table with, what we believe to be, the most common scenarios. The available suggestions are:

        Username & Password
        Email & Password
        Page 1: Username, Page 2: Password
        Page 1: Email, Page 2: Password
        Page 1: Password, Page 2: TOTP
        Page 1: Username & Password, Page 2: TOTP
        Page 1: Email & Password, Page2: TOTP
        Page 1: Username, Page 2: Password, Page 3: TOTP
        Page 1: Email, Page 2: Password, Page 3: TOTP

The scripts themselves actually look like this, and you’ll see these displayed as the Command field’s value once selected:

        #[username]<tab>#[password]<enter>
        #[email]<tab>#[password]<enter>
        #[username]<enter><wait2>#[password]<enter>
        #[email]<enter><wait2>#[password]<enter>
        #[password]<enter><wait2>#[totp]<enter>
        #[username]<tab>#[password]<enter><wait3>#[totp]<enter>
        #[email]<tab>#[password]<enter><wait3>#[totp]<enter>
        #[username]<enter><wait2>#[password]<enter><wait3>#[totp]<enter>
        #[email]<enter><wait2>#[password]<enter><wait3>#[totp]<enter>

As the syntax suggests, you can enter your own command matching your own custom label names, for instance:

#[groupid]<tab>#[login]<enter><wait3>#[password]<enter>

The <waitN> command is useful after <enter> when you have to fill out multiple forms in succession, and need to allow time for the next form to load. As always, if you have questions, suggestions or feedback, please let us know at support@zetetic.net.

Trouble Shooting

If you are having trouble enabling or using Secret Agent to insert your passwords in other apps we have a troubleshooting document available listing known issues and work-arounds. And as always, feel free to contact us directly for help.