s1ft command line reference

The s1ft command reads your meetings from the terminal. It prints text or JSON. AI agents use it, and you can use it too. This page lists every command, every option, the defaults, and the exit codes. For the agent setup, see Connect AI agents. For the fields in the data files, see Meeting data files.

What the command line does

• The command only reads. It changes no meeting file.
• The only file it writes is cli.json, and only when you run s1ft config dir <path>.
• The command reads meeting.json, transcript.json and telemetry.json.
• The command never reads transcript.md or history.json.
• Only meetings recorded with S1ft 1.3 or later appear. A folder without meeting.json is not a meeting for the command.

Install and link

The command is inside the app, at S1ft.app/Contents/Helpers/s1ft. To use it as s1ft in your terminal, link it to ~/.local/bin/s1ft. You do not need administrator rights. You can run these commands again at any time.

mkdir -p ~/.local/bin
ln -sf /Applications/S1ft.app/Contents/Helpers/s1ft ~/.local/bin/s1ft

If ~/.local/bin is not in your PATH, call ~/.local/bin/s1ft with the full path. The s1ft skill from Connect AI agents does this link for you.

Version

Show the version of the command:

s1ft --version

The output has this form:

s1ft 1.3.0

The command ships with the app, so this is the app version. Add --json for a JSON object:

s1ft --version --json

{"buildDate":"2026-10-13","commit":"abc1234","treeState":"clean","version":"1.3.0"}

The object has the keys buildDate, commit, treeState and version. It has no schemaVersions key. Read the schemaVersion of each data file from the file itself.

Folder order

Each command that reads meetings looks in one meetings folder. s1ft picks the folder in this order. The first match wins.

1. The --dir <path> option.
2. The meetingsDir key in ~/Library/Application Support/s1ft/cli.json.
3. The output folder you set in the s1ft app (the outputDir setting).
4. ~/Documents/s1ft Meetings.

To see which folder is in use, run s1ft config dir.

meetings list

List your meetings, newest first.

s1ft meetings list [--since <date>] [--until <date>] [--attendee <value>] [--json] [--dir <path>]

The text output has one line for each meeting. A tab separates the three columns: the meeting id, the start time and the name.

6f1d2c3a-8b4e-4f10-9a7c-2d5e1b0c9a11	2026-07-16T10:00:00Z	Weekly sync

The id is the id from meeting.json. The other commands take this id.

meetings search

Find meetings by text.

s1ft meetings search <text> [--since <date>] [--until <date>] [--attendee <value>] [--json] [--dir <path>]

The command looks for <text> in the meeting name and in the text of the transcript segments in transcript.json. Letter case and accents do not count. The options and the output are the same as for meetings list, with --attendee included.

—attendee

Use --attendee <value> with meetings list or meetings search to keep only the meetings with a given attendee. The option is available from S1ft 1.3.0.

s1ft meetings list --attendee [email protected]
s1ft meetings search budget --attendee @example.com
s1ft meetings list --attendee garcia

The command reads the attendees from the calendarEvents in meeting.json. A meeting stays in the result if any attendee of any of its events agrees with the value. There are three match rules:

Letter case never counts. An attendee with no name or no email never agrees by that field.

The command checks --attendee after --since and --until. Use the option at most once. The command exits with code 4 when the value is empty, when you repeat the option, or when you use it with another command.

meetings show

Show one meeting.

s1ft meetings show <id> [--json] [--dir <path>]

The text output has the name, id, platform, start, end and folder of the meeting. It also lists the paths of meeting.json, transcript.json and telemetry.json, and then the transcript, one line for each segment. A file that does not exist shows -.

The JSON output has the keys meeting (the content of meeting.json), transcript (the content of transcript.json) and files (the three file paths). A missing item is null.

If no meeting has the id, the command exits with code 3.

voice stats

Calculate voice numbers for one meeting from telemetry.json (version 2). The command saves nothing.

s1ft voice stats <id> [--silence-threshold-dbfs <dbfs>] [--min-silence-ms <ms>] [--percentiles <list>] [--json] [--dir <path>]

Example:

s1ft voice stats 6f1d2c3a-8b4e-4f10-9a7c-2d5e1b0c9a11 --silence-threshold-dbfs -45 --min-silence-ms 500 --percentiles 25,50,75

If the meeting has no telemetry.json of version 2, the command exits with code 3.

config dir

Show or set the meetings folder.

Show the folder in use

s1ft config dir [--dir <path>] [--json]

The command prints the folder and where the folder came from:

/Users/you/Documents/s1ft Meetings
source: default

The source line is one of --dir, config, app setting or default. These match the four steps in Folder order. With --json, the output is:

{"directory": "/Users/you/Documents/s1ft Meetings", "source": "default"}

Save a folder

s1ft config dir <path> [--json]

The command saves the folder as meetingsDir in ~/Library/Application Support/s1ft/cli.json. It keeps the other keys of that file. It writes the file in one step. It does not change the settings of the s1ft app. The command then prints the same report as above, with source: config, and exits with code 0.

If the path is not an existing folder, the command exits with code 3 and prints this line on stderr. cli.json does not change.

s1ft: The folder does not exist: <path>

This form does not take the --dir option.

—since and —until

Both options take one of these formats:

With a day, --since 2026-07-16 starts at 00:00 of that day, and --until 2026-07-16 ends at the end of that day. With a time, the meeting start is compared with that exact time, and the time itself is included. A date and time without a time zone is not valid. Any other value exits with code 4.

JSON output

With --json, meetings list and meetings search print one object:

{
  "directory": "/Users/you/Documents/s1ft Meetings",
  "meetings": [
    {
      "directory": "/Users/you/Documents/s1ft Meetings/2026-07-16 Weekly sync",
      "end": "2026-07-16T10:30:00Z",
      "id": "6f1d2c3a-8b4e-4f10-9a7c-2d5e1b0c9a11",
      "name": "Weekly sync",
      "platform": "us.zoom.xos",
      "start": "2026-07-16T10:00:00Z"
    }
  ]
}

The top-level directory key is the meetings folder that the command searched. It is always there, also when the result is empty. In that case meetings is an empty array. The command prints the object on one line. The example above is formatted to be easy to read.

Exit codes and messages

On an error, the command prints one message on stderr, and stdout is empty. A usage error also prints Try 's1ft --help'.

Empty result

If meetings list or meetings search finds no meeting, stdout stays as it is (nothing in text mode, an empty meetings array in JSON mode) and the exit code is 0. The command prints one line on stderr:

s1ft: No meetings found in <folder>. Only meetings recorded with S1ft 1.3 or later appear.

Folder does not exist

If the meetings folder does not exist, meetings list, meetings search, meetings show and voice stats exit with code 3 and print this line on stderr:

s1ft: The meetings folder does not exist: <folder>. Use --dir <path> or run 's1ft config dir <path>'.

To fix it, run s1ft config dir <path> with the folder that holds your meetings. For where s1ft stores meetings, see Finding your recordings.

What’s next

• Connect AI agents — Install the s1ft skills and run them after each meeting.
• Meeting data files — Every field of meeting.json, transcript.json and telemetry.json.
• Settings reference — The output folder in the app.