Notta CLI

A command-line tool for audio/video transcription and record management through Notta.

Installation

npm install -g @notta-labs/notta-cli
notta --version  # Verify installation

Core Commands

Command	Purpose	Usage
auth setup	OAuth login	notta auth setup [--env prod] [--port 8888]
transcribe	Upload & transcribe file	notta transcribe <file> [--language en-US]
status	Check transcription status	notta status <record_id> [--wait]
view	Get transcription result	notta view <record_id>
search	Search records by keyword	notta search [keyword] [--page 1] [--page_size 10]
list	List records/folders	notta list [group_id] [--order_by created] [--order_type desc]

Quick Start: Transcribe a File

# 1. Start transcription (returns record_id)
notta transcribe /absolute/path/to/file.mp4 --language en-US

# 2. Wait for completion
notta status <record_id> --wait

# 3. Get result (save to file for large outputs)
notta view <record_id> > result.json

Output Format

All commands output results wrapped in a JSON envelope:

{
  "error_code": 0,
  "message": "",
  "data": {
    "record_id": "abc123",
    "s3_url": "https://..."
  }
}

Extract data with jq:

notta transcribe /path/to/file.mp4 | jq '.data'
notta transcribe /path/to/file.mp4 | jq '.data.record_id'

Key Points

• File paths must be absolute, not relative
• Default language is ja-JP; specify --language for other languages
• Credentials stored at ~/.config/notta_cli/credentials.json
• Transcription timeout is 10 minutes
• File name becomes record name: meeting.mp4 → record named meeting

Pre-flight: Credential Check (MANDATORY)

Before running ANY notta command (except notta auth setup), you MUST first check whether credentials exist:

test -f ~/.config/notta_cli/credentials.json && echo "OK" || echo "MISSING"

• If OK: proceed with the requested command.
• If MISSING: attempt automatic recovery using the following steps:

Auto-recovery Steps

1. Check if notta is installed:

   command -v notta &>/dev/null && echo "INSTALLED" || echo "NOT_INSTALLED"

2. If NOT_INSTALLED: install it first, then proceed to step 3:

   npm install -g @notta-labs/notta-cli

   If npm is also unavailable, stop and inform the user they need Node.js/npm installed.
3. Run notta auth setup: this is an interactive OAuth flow that opens a browser. Inform the user that authentication is starting, then run:

   notta auth setup

4. Verify credentials were created:

   test -f ~/.config/notta_cli/credentials.json && echo "OK" || echo "STILL_MISSING"

   • If OK: continue with the user's original request.
   • If STILL_MISSING: inform the user that authentication failed and ask them to try manually with ! notta auth setup.

Authentication

notta auth setup

Before using any command, credentials must be established at ~/.config/notta_cli/credentials.json.

The CLI automatically refreshes expired tokens. Only re-run notta auth setup if token refresh fails.

Handling Large Results

For large JSON outputs (>10MB):

# Always redirect to file
notta view <record_id> > result.json

# Check file size
ls -lh result.json

# Read incrementally with file tool
file read result.json --range [1, 100]  # First 100 lines
file read result.json --range [100, 200]  # Next 100 lines

# Extract specific fields with jq
jq '.data.text' result.json > transcription_only.txt
jq '.data.content[] | {speaker: .speaker_name, text}' result.json > speakers.json

Debugging

All API requests are logged to stderr in curl format:

# View API requests and responses
notta transcribe /path/to/file.mp4 2>&1 | grep -E "\[curl\]|\[resp\]"

Error Recovery

Error	Solution
"Authorization required"	Run notta auth setup to re-authenticate
"Validation error"	Verify absolute file paths and required parameters
"no available server"	Backend temporarily down; retry in 1 minute
Status polling timeout (10 min)	Check status without --wait: notta status <record_id>
S3 upload fails	Run notta config to check S3 credentials; if expired, delete ~/.config/notta_cli/credentials.json and re-authenticate

Supported Languages

sl-SI, hr-HR, sr-RS, bg-BG, ro-RO, hu-HU, lt-LT, lv-LV, da-DK, nb-NO, sv-SE, fi-FI, is-IS, tr-TR, ar-AE, ar-EG, fa-IR, he-IL, hy-AM, az-AZ, ka-GE, el-GR, gu-IN, kn-IN, ta-IN,
zh-CN, zh-TW, zh-HK, en-US, ja-JP, ko-KR, vi-VN, th-TH, hi-IN, id-ID, jv-ID, ms-MY, fil-PH, ne-NP, pt-PT, es-ES, fr-FR, de-DE, it-IT, nl-NL, ru-RU, uk-UA, pl-PL, cs-CZ, sk-SK, te-IN, ur-IN, bn-IN, km-KH, lo-LA, si-LK, sw-KE, zu-ZA, af-ZA, am-ET, eu-ES, ca-ES, gl-ES, su-ID

Command Behaviors

Optional Parameters

• notta status (no record_id) → returns empty array []
• notta view (no record_id) → returns empty array []
• notta search (no keyword) → returns empty array []

Port Configuration

Default OAuth callback port is 9999. If occupied, CLI automatically selects the next available port:

notta auth setup