fix(search): accept --offset, which the more-results hint suggests

README.md

@@ -112,7 +112,7 @@ Self-hosted instances: pass `--base-url` or set `OUTLINE_URL` (you can still pro
 
 ```bash
 # Search
-ol search "query" --limit 10 --collection <id> --status published
+ol search "query" --limit 10 --offset 10 --collection <id> --status published
 
 # Documents (alias: ol doc)
 ol document list --collection <id> --sort updatedAt --direction DESC

skills/outline-cli/SKILL.md

@@ -41,6 +41,7 @@ Documents can be referenced by:
 ```bash
 ol search "query"
 ol search "query" --limit 10
+ol search "query" --offset 25          # next page of results
 ol search "query" --collection <id>
 ol search "query" --status published
 ol search "query" --json

src/commands/commands.test.ts

@@ -45,6 +45,26 @@ describe('search command', () => {
         expect(apiRequest).toHaveBeenCalledWith('documents.search', {
             query: 'test query',
             limit: 10,
+            offset: 0,
+        })
+    })
+
+    it('passes --offset, which the "more results" hint points to', async () => {
+        const { apiRequest } = await import('../lib/api.js')
+        ;(apiRequest as ReturnType<typeof vi.fn>).mockResolvedValue({
+            data: [],
+            pagination: { offset: 25, limit: 25 },
+        })
+
+        const { registerSearchCommand } = await import('./search.js')
+        const program = createTestProgram(registerSearchCommand)
+
+        await program.parseAsync(['node', 'ol', 'search', 'test query', '--offset', '25'])
+
+        expect(apiRequest).toHaveBeenCalledWith('documents.search', {
+            query: 'test query',
+            limit: 25,
+            offset: 25,
         })
     })
 

src/commands/search.ts

@@ -38,6 +38,7 @@ export function registerSearchCommand(program: Command): void {
         .command('search <query>')
         .description('Search documents')
         .option('--limit <n>', 'Max results', '25')
+        .option('--offset <n>', 'Pagination offset', '0')
         .option('--collection <id>', 'Filter by collection ID')
         .option('--status <status>', 'Filter by status (published|draft|archived)')
         .option('--json', 'Output JSON')
@@ -47,6 +48,7 @@ export function registerSearchCommand(program: Command): void {
             const body: Record<string, unknown> = {
                 query,
                 limit: Number(opts.limit),
+                offset: Number(opts.offset),
             }
             if (opts.collection) body.collectionId = opts.collection
             if (opts.status) body.statusFilter = [opts.status]

src/lib/output.test.ts

@@ -44,6 +44,24 @@ describe('output', () => {
         ])
     })
 
+    it('outputList human mode shows the pagination hint', () => {
+        outputList([item], formatter, keys, {}, { offset: 0, limit: 1, nextPath: '/next' })
+        expect(lines(log).join('\n')).toContain('use --offset 1')
+    })
+
+    it('outputList json mode keeps the pagination hint out of stdout', () => {
+        const error = captureConsole('error')
+        outputList(
+            [item],
+            formatter,
+            keys,
+            { json: true },
+            { offset: 0, limit: 1, nextPath: '/next' },
+        )
+        expect(JSON.parse(lines(log).join('\n'))).toEqual([{ id: '1', name: 'Test' }])
+        expect(lines(error).join('\n')).toContain('use --offset 1')
+    })
+
     it('getOutputOptions parses flags', () => {
         expect(getOutputOptions({ json: true, full: true, ndjson: false })).toEqual({
             json: true,

src/lib/output.ts

@@ -66,11 +66,15 @@ export function outputList<T extends object>(
     }
 
     if (pagination?.nextPath && !opts.ndjson) {
-        console.log(
-            chalk.dim(
-                `\n(more results available — use --offset ${pagination.offset + pagination.limit})`,
-            ),
+        const hint = chalk.dim(
+            `\n(more results available — use --offset ${pagination.offset + pagination.limit})`,
         )
+        // In JSON mode stdout holds the JSON itself, so the hint goes to stderr to keep it parseable.
+        if (opts.json) {
+            console.error(hint)
+        } else {
+            console.log(hint)
+        }
     }
 }
 

src/lib/skills/content.ts

@@ -40,6 +40,7 @@ Documents can be referenced by:
 \`\`\`bash
 ol search "query"
 ol search "query" --limit 10
+ol search "query" --offset 25          # next page of results
 ol search "query" --collection <id>
 ol search "query" --status published
 ol search "query" --json