ox import

Import a document, media file, or video URL into team context for onboarding and knowledge sharing. Audio and video files upload to SageOx as recordings, which are transcribed and summarized server-side. Other files are stored with LFS-backed content and git-tracked metadata in the Team Context repo.

Usage

terminal

The team is auto-discovered from the current repo. Use --team to override.

Examples

Import a document

terminal

# Import a PDF

# Import with pre-extracted text stored alongside the original

# Override the filename-derived title

# Import with a specific date

# Import to a specific team

Import an audio or video file

terminal

# Upload a recording, then transcribe and summarize it

Large files upload in parallel parts with retries. Files over 50 MB report progress on stderr.

Import a video URL

terminal

# Import a Loom video

# Import a Cap recording

# Import a direct video URL

Check import status

terminal

# List up to 50 media and URL imports with their IDs

# Check processing status once

# Watch until processing completes

Flags

Flag	Description
`--text <file>`	Path to pre-extracted text/markdown for indexing, stored as `extracted.md` beside the original (keeps audio/video on the document path)
`--date <YYYY-MM-DD>`	Date for filing, or when audio/video was recorded (default: auto-detect from metadata)
`--title <text>`	Display title (defaults to the filename for file imports)
`--team <id>`	Team ID (or slug/name when inside a repo)
`--force`	Re-import even if content hash already exists
`--status <id>`	Check processing status of a media or URL import (use `--list` to find IDs)
`--watch`	Poll `--status` until processing completes or fails
`--list`	List media and URL imports (up to 50) and their processing status. Document imports are not listed

Supported file types

Type	Extensions
Documents	`.pdf`, `.docx`, `.md`, `.txt`, `.html`
Data	`.json`, `.yaml`, `.csv`
Images	`.png`, `.jpg`, `.jpeg`
Audio and video (uploaded as recordings)	`.m4a`, `.mp3`, `.wav`, `.webm`, `.ogg`, `.opus`, `.flac`, `.aac`, `.wma`, `.mp4`, `.mov`, `.m4v`

Supported video platforms

Loom: https://www.loom.com/share/...
Cap: https://cap.link/...
Direct URLs: Any accessible .mp4, .webm, etc.

How file imports work

These steps apply to documents and other non-media files:

Upload, Content is uploaded to LFS (Git Large File Storage)
Pointer, A small pointer file is committed to team context
Metadata: metadata.json tracks title, content type, date, sidecars
Push, Changes are pushed to the team context repo

Files are stored at:

data/docs/YYYY/MM/DD/<slug>/
├── metadata.json      # Document metadata
├── original.pdf       # LFS pointer to original
└── extracted.md       # LFS pointer to extracted text (if provided)

How URL imports work

Submit, URL is sent to SageOx cloud for processing
Download, Cloud downloads the video
Transcribe, Audio is transcribed
Summarize, AI generates summary and key points
Store, Results are stored in team context

Track progress with --status and --watch.

What not to import

Knowledge Bubbles are Curator-authored syntheses, not an import target. For behavioral rules, see ox guide team-rules: rules go in agents/rules/, not through ox import.

Deduplication

Imports are deduplicated by content hash. If you try to import a file that's already been imported, ox will skip it:

terminal

Already imported (id: architecture-review). Use --force to reimport.

Use --force to reimport anyway.

What's next

ox query - Search imported documents
ox sync - Sync team context
ox guide - Read ox guide team-rules for sharing rules instead of documents

On this page