Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,13 @@ ol document move <urlId> --collection <target-id>
ol document archive <urlId>
ol document unarchive <urlId>

# Attachments (alias: ol attach)
ol attachment upload ./plan.pdf --doc <ref> # prints the markdown link for the file
ol attachment upload ./plan.pdf --doc <ref> --append # also appends that link to the document
ol attachment list --doc <ref> # attachments and images linked in a document
ol attachment download <id|link> # saves under the original name; --output <path|dir|->, --force
ol attachment delete <id|link> --confirm

# Collections (alias: ol col)
ol collection list
ol collection get <id>
Expand Down
29 changes: 28 additions & 1 deletion skills/outline-cli/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: outline-cli
description: "Search and manage Outline wiki documents and collections via the ol CLI"
description: "Search and manage Outline wiki documents, collections and attachments via the ol CLI"
---

# Outline CLI (ol)
Expand All @@ -15,6 +15,8 @@ Use this skill when the user wants to interact with their Outline wiki/knowledge
- `ol doc open <id>` - Open document in browser
- `ol doc create --title "Title" --collection <id>` - Create document
- `ol col list` - List collections
- `ol attachment upload <file> --doc <ref>` - Upload a file to a document
- `ol attachment download <id>` - Download an attachment
- `ol account` - List stored accounts; `ol account use <id|name>` sets the default

## Output Formats
Expand Down Expand Up @@ -83,6 +85,23 @@ ol col update <id> --name "New Name"
ol col delete <id> --confirm
```

### Attachments (alias: attach)
```bash
ol attachment upload ./plan.pdf --doc <ref> # Upload; prints the markdown link to paste into the doc
ol attachment upload ./plan.pdf --doc <ref> --append # Upload and append the link to the end of the doc
ol attachment upload ./photo.jpg --doc <ref> --name "Site photo.jpg" --content-type image/jpeg
ol attachment upload ./plan.pdf --doc <ref> --json # {id, name, contentType, size, documentId, url, markdown}
ol attachment list --doc <ref> # Attachments and images linked in the doc (id, name, size, type)
ol attachment list --doc <ref> --json
ol attachment download <id|link> # Save under the original file name in the current directory
ol attachment download <id|link> --output ./files/ # Into a folder (created when the path ends in /), or --output <path>
ol attachment download <id|link> --output - # Write the file to stdout
ol attachment download <id|link> --force # Overwrite an existing file (refused otherwise)
ol attachment delete <id|link> --confirm # Delete the file; links to it in documents stay
```
An attachment is referenced by its ID or any link containing `/api/attachments.redirect?id=<id>`. Images are linked as `![alt](/api/attachments.redirect?id=<id>)`, other files as `[<name> <bytes>](/api/attachments.redirect?id=<id>)`; keep that form when writing it into a document yourself.
`attachment list` reads those links from the document text, so a plain link whose text ends in a number (`[report 2024](…attachments.redirect?id=…)`) lists as name `report`, size 2024, and links to another Outline instance's attachments are listed but cannot be downloaded from this one.

### Authentication
```bash
ol auth login # OAuth login (opens browser); prompts for base URL + client ID if needed
Expand Down Expand Up @@ -149,6 +168,14 @@ ol doc update <id> --file doc.md --if-updated-at "$ts"
```
If the document was saved after `$ts`, the update fails with `DOCUMENT_CHANGED`, or with Outline's "Document has been modified since the provided revision" when the save lands during the update; re-read and retry. Edits not yet saved from an open editor are not detected.

### Attach a file and download every attachment of a document
```bash
ol attachment upload ./drawing.pdf --doc <ref> --append
ol attachment list --doc <ref> --json | jq -r '.[].id' | while read -r id; do
ol attachment download "$id" --output "./downloads/$id/" # one folder each: names often repeat
done
```

### List all collections and their documents
```bash
ol col list --json
Expand Down
190 changes: 190 additions & 0 deletions src/commands/attachment.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,190 @@
import { captureConsole, createTestProgram } from '@todoist/cli-core/testing'
import { type MockInstance, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { lines, mockOutlineAuthModule } from '../_fixtures/testing.js'

vi.mock('../lib/auth.js', () => mockOutlineAuthModule())

vi.mock('../lib/api.js', () => ({
apiRequest: vi.fn(),
}))

vi.mock('../lib/refs.js', () => ({
resolveDocumentRef: vi.fn(async () => ({
id: 'doc-1',
title: 'Spec',
url: '/doc/spec-abc123',
urlId: 'abc123',
})),
}))

vi.mock('../lib/attachments.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../lib/attachments.js')>()),
uploadAttachment: vi.fn(),
downloadAttachment: vi.fn(),
}))

const ID = '3e7bbd8c-907b-4b10-9160-9b820d5ce255'

const uploaded = {
id: ID,
name: 'plan.pdf',
contentType: 'application/pdf',
size: 2048,
documentId: 'doc-1',
url: `/api/files.get?key=uploads/${ID}/plan.pdf`,
}

async function mocks() {
const { apiRequest } = await import('../lib/api.js')
const attachments = await import('../lib/attachments.js')
return {
apiRequest: apiRequest as ReturnType<typeof vi.fn>,
uploadAttachment: attachments.uploadAttachment as ReturnType<typeof vi.fn>,
downloadAttachment: attachments.downloadAttachment as ReturnType<typeof vi.fn>,
}
}

async function run(...args: string[]) {
const { registerAttachmentCommand } = await import('./attachment.js')
const program = createTestProgram(registerAttachmentCommand)
await program.parseAsync(['node', 'ol', ...args])
}

describe('attachment commands', () => {
let log: MockInstance

beforeEach(() => {
log = captureConsole()
})

afterEach(() => {
vi.clearAllMocks()
vi.restoreAllMocks()
})

it('upload passes the file and options and prints the markdown link', async () => {
const { uploadAttachment, apiRequest } = await mocks()
uploadAttachment.mockResolvedValue(uploaded)

await run(
'attachment',
'upload',
'./plan.pdf',
'--doc',
'spec',
'--name',
'plan.pdf',
'--content-type',
'application/pdf',
)

expect(uploadAttachment).toHaveBeenCalledWith({
filePath: './plan.pdf',
documentId: 'doc-1',
name: 'plan.pdf',
contentType: 'application/pdf',
})
expect(apiRequest).not.toHaveBeenCalled()
const out = lines(log).join('\n')
expect(out).toContain('Uploaded: plan.pdf')
expect(out).toContain(`[plan.pdf 2048](/api/attachments.redirect?id=${ID})`)
})

it('upload --append appends the link with the version-safe append flag', async () => {
const { uploadAttachment, apiRequest } = await mocks()
uploadAttachment.mockResolvedValue({ ...uploaded, contentType: 'image/png', name: 'a.png' })
apiRequest.mockResolvedValue({ data: {} })

await run('attach', 'upload', 'a.png', '--doc', 'spec', '--append')

expect(apiRequest).toHaveBeenCalledWith('documents.update', {
id: 'doc-1',
text: `\n\n![a.png](/api/attachments.redirect?id=${ID})`,
append: true,
})
expect(lines(log).join('\n')).toContain('Appended to: Spec')
})

it('upload --json prints the attachment with its redirect URL and markdown', async () => {
const { uploadAttachment } = await mocks()
uploadAttachment.mockResolvedValue(uploaded)

await run('attachment', 'upload', 'plan.pdf', '--doc', 'spec', '--json')

expect(JSON.parse(lines(log)[0])).toEqual({
...uploaded,
url: `/api/attachments.redirect?id=${ID}`,
markdown: `[plan.pdf 2048](/api/attachments.redirect?id=${ID})`,
})
})

it('download passes output and force through', async () => {
const { downloadAttachment } = await mocks()
downloadAttachment.mockResolvedValue({ id: ID, name: 'a.pdf', path: 'out/a.pdf', size: 10 })

await run('attachment', 'download', ID, '--output', 'out', '--force')

expect(downloadAttachment).toHaveBeenCalledWith(ID, { output: 'out', force: true })
expect(lines(log)[0]).toContain('Downloaded: out/a.pdf')
})

it('download --output - prints nothing besides the file content', async () => {
const { downloadAttachment } = await mocks()
downloadAttachment.mockResolvedValue({ id: ID, name: 'a.pdf', path: '-', size: 10 })

await run('attachment', 'download', ID, '--output', '-')

expect(downloadAttachment).toHaveBeenCalledWith(ID, { output: '-' })
expect(log).not.toHaveBeenCalled()
})

it('list reads attachment links from the document text', async () => {
const { apiRequest } = await mocks()
apiRequest.mockResolvedValue({
data: {
id: 'doc-1',
text: `See [plan.pdf 2048](/api/attachments.redirect?id=${ID})`,
},
})

await run('attachment', 'list', '--doc', 'spec', '--json')

expect(apiRequest).toHaveBeenCalledWith('documents.info', { id: 'doc-1' })
expect(JSON.parse(lines(log)[0])).toEqual([
{
id: ID,
name: 'plan.pdf',
size: 2048,
type: 'file',
url: `/api/attachments.redirect?id=${ID}`,
},
])
})

it('list says so when a document has no attachments', async () => {
const { apiRequest } = await mocks()
apiRequest.mockResolvedValue({ data: { id: 'doc-1', text: 'Plain text' } })

await run('attachment', 'list', '--doc', 'spec')

expect(lines(log).join('\n')).toContain('No attachments found.')
})

it('delete requires --confirm', async () => {
const { apiRequest } = await mocks()
await expect(run('attachment', 'delete', ID)).rejects.toThrow(
'Delete operation requires confirmation.',
)
expect(apiRequest).not.toHaveBeenCalled()
})

it('delete accepts a link and deletes by ID', async () => {
const { apiRequest } = await mocks()
apiRequest.mockResolvedValue({ data: undefined })

await run('attachment', 'delete', `/api/attachments.redirect?id=${ID}`, '--confirm')

expect(apiRequest).toHaveBeenCalledWith('attachments.delete', { id: ID })
expect(lines(log)[0]).toBe('Deleted.')
})
})
Loading
Loading