Make Raven work your way

Your first action

These features are in the current source build. Check the changelog for availability in your downloaded version. Put init.js beside your config.toml, normally in ~/.config/raven-term/. If you set XDG_CONFIG_HOME or RAVEN_CONFIG, use the resulting config directory.

// ~/.config/raven-term/init.js
raven.action({
  name: 'scratch',
  title: 'Open a scratch terminal',
  args: { directory: 'string' },
  run(context, args) {
    return raven.call('run_in_pane', {
      placement: 'tab',
      cwd: args.directory,
      command: ['/bin/sh']
    });
  }
});
raven.bind('ctrl+b>s', 'scratch', { directory: '/tmp' });

raven-term config check
raven-term config reload
raven-term do scratch '{"directory":"/tmp"}'

Open the command palette and choose Open a scratch terminal. Enter {"directory":"/tmp"} when prompted. Or press Control+B, then S to use the bound directory. actions and keymap show what is registered.

Typed arguments and safe reloads

Arguments support string, number, integer, boolean, object, array, and any. Append ? to make an argument optional. Unknown or invalid arguments are rejected before the action runs.

Configuration loading registers actions, modes, and bindings. Effects, event handlers, and timers belong inside an action or standalone script. A failed reload keeps your last working configuration. Reloading requires the local socket; remote callers can invoke installed actions but cannot upload or reload code. Raven does not automatically load scripts from a terminal’s working directory.

Key sequences and modes

Separate chords with >. A prefix waits up to 1.5 seconds for the next key. Escape cancels the sequence or pops the active mode. Modes let the same keys do different work; an exclusive mode consumes unmatched keys, and a one-shot mode exits after a match. The window shows the active mode.

raven.mode('navigate', { exclusive: true });
raven.bind('ctrl+b>n', 'client.mode.push', {
  mode: 'navigate', one_shot: true
});
raven.bind('j', 'client.NextPane', {}, { mode: 'navigate' });
raven.bind('k', 'client.PrevPane', {}, { mode: 'navigate' });

Use physical key names: ctrl, alt, shift, super, letters, digits, arrows, and F1–F12. Ambiguous prefixes and duplicate normalized bindings are rejected. Explicit user shortcuts keep their precedence.

Scripts, events, and timers

Run a file with raven-term do build.js, an expression with do -e, or stdin with do -. Relative ES module imports stay inside the entry file’s directory. Package imports and asynchronous callbacks are not supported.

// build.js
const job = raven.call('run_in_pane', {
  placement: 'background', command: ['make', 'test']
});
raven.on('terminal.child_exited', event => {
  if (event.pane === job.pane) {
    raven.result(event.data);
    raven.stop(event.data.exit_code);
  }
});
const reminder = raven.every(1000, () => raven.log('Still running'));
raven.after(10000, () => reminder.cancel());

raven.call calls the daemon API; raven.invoke runs another action. raven.on subscribes to events, raven.wait waits for a matching event, and after and every create cancelable timers. Events include pane and space changes, terminal titles and directories, agent states, bells, process exits, and program status.

For an external consumer, raven-term events returns pages with resume cursors. Save the returned cursor even after a filtered empty page. The daemon keeps 4,096 events; a gap or restart returns an explicit error so you can refresh state and start a new cursor.

Process results and the API

raven-term api list
raven-term api describe run_in_pane
raven-term run --wait -- make test
raven-term wait 3 --timeout 60

API calls validate arguments against the daemon’s tool schemas. run --wait returns the child’s actual exit code; wait returns 124 on timeout. Fast exits are retained. A daemon restart or replaced process is reported instead of being mistaken for the original process. This is separate from agent wait, which observes agent quietness.

Where your code runs

Installed actions run as the daemon owner. Standalone scripts run on the machine invoking the CLI; --remote NAME directs their API calls to a saved remote. raven.exec(argv, options) starts a local subprocess with no implicit shell and supports cwd, env, and timeout_ms.

Callbacks have an instruction budget. Installed actions bound native effects to 25 seconds; subprocess output is limited to 1 MiB per stream. These limits are not a security sandbox: install scripts you trust with your account’s access. See Data and connections.