You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat: add attachment upload, download, list and delete - #175
Adds an ol attachment command group (alias attach) so files can be moved in and out of documents from the CLI:
ol attachment upload ./plan.pdf --doc <ref> [--append] [--name] [--content-type] [--json]
ol attachment list --doc <ref> [--json|--ndjson]
ol attachment download <id|link> [--output <path|dir|->] [--force] [--json]
ol attachment delete <id|link> --confirm
upload registers the file with attachments.create, then sends it to the target Outline returns. It handles all three: Outline's own files.create (local storage), a presigned S3 POST, and a presigned PUT (AWS_S3_UPLOAD_METHOD=put). If the transfer fails, the registered attachment is deleted again. It prints the Markdown link in the same form the editor writes ( for images, [name bytes](…) for files). --append adds that link to the end of the document.
list reads the attachment and image links from the document text. attachments.list only returns the caller's own uploads, so it would miss files other people attached.
download saves the file under its server file name (base name only), into a directory, to a path, or to stdout. It refuses to overwrite an existing file unless --force is passed, and removes partial files on failure.
delete deletes by ID or link.
Implementation notes
api.ts: token resolution and the 401 refresh-and-retry move into shared helpers. The new authorizedFetch uses them for non-JSON transfers. It only attaches the bearer token when the URL is on the instance's own origin, so the token never goes to S3. apiRequest behaves as before, and its existing tests are unchanged.
The multipart body is built as a Blob, not a FormData. The bundled undici fetch from http-dispatcher.ts does not accept Node's global FormData and sends it as the string [object FormData]; Outline then rejects it with body: Invalid input: expected object, received string. A Blob built from the file's lazy openAsBlob has a known Content-Length (presigned S3 POSTs reject chunked bodies), and the file is never read into memory.
Downloads follow the attachments.redirect redirect by hand (redirect: 'manual'), which is what keeps the token on the instance.
--append sends append: true rather than editMode: 'append'. Every server with text edits understands append (newer ones map it to editMode), whereas an older server would drop an unknown editMode and replace the whole document with the link.
Skill content, SKILL.md (via sync:skill) and the README are updated.
Testing
npm run type-check, lint:check, format:check, check:skill-sync and npm test all pass. There are 284 tests, 28 of them new, covering upload (local, S3 POST, PUT, older servers without mode, cleanup on failure, missing file), download (manual redirect, directory output, overwrite refusal, errors, redirect loop), authorizedFetch token scoping and refresh, the link parser, multipart encoding, and the command surface.
Tested by hand against a self-hosted Outline 1.12.0 with FILE_STORAGE=local, using an API key:
uploaded text, PNG, a 3 MB binary, and a PDF with spaces and a non-ASCII name;
downloaded them to a file, a directory and stdout, and checked each was byte-identical with cmp;
checked list output, the overwrite refusal, delete, and errors for unknown IDs.
The S3 POST and PUT paths are covered by unit tests only; I didn't test them against real S3.
This change was written with an AI coding assistant, then reviewed and tested as described above.
Adds an `ol attachment` (alias `attach`) command group:
- upload <file> --doc <ref> [--name] [--content-type] [--append] [--json]
- download <id|link> [--output <path|dir|->] [--force] [--json]
- list --doc <ref> [--json|--ndjson]
- delete <id|link> --confirm
Uploads register the file with attachments.create, then send it to the
returned target: Outline's own files.create (local storage), a presigned
S3 POST, or a presigned PUT. The multipart body is built as a Blob because
the bundled undici fetch does not accept Node's global FormData. A failed
transfer deletes the registered attachment.
Downloads follow the attachments.redirect redirect by hand so the bearer
token is only sent to the Outline instance, never to third-party storage.
api.ts gains authorizedFetch, sharing token resolution and the 401 refresh
retry with apiRequest.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Download error cleanup can delete a pre-existing file without --force, and regex-based Markdown scanning misses valid attachments while including links from code examples.
Adds attachment management to the Outline CLI through ol attachment (alias attach), extending document workflows with file transfers and linked-attachment discovery.
Changes:
Adds upload, download, list, and confirmed-delete commands, including optional Markdown-link appending.
Introduces local-storage and S3 transfer support with shared authentication handling and download safeguards.
Adds tests and updates the README and agent command references.
File
Description
src/lib/skills/content.ts
Adds attachment commands and workflow examples to the agent reference.
src/lib/errors.ts
Adds attachment-related error codes.
src/lib/attachments.ts
Implements transfers, link parsing, multipart encoding, and file handling.
src/lib/attachments.test.ts
Tests attachment helpers and transfer behavior.
src/lib/api.ts
Shares authentication logic and adds origin-scoped raw requests.
src/lib/api.test.ts
Tests raw-request token scoping and refresh behavior.
src/index.ts
Registers the attachment command group.
src/commands/attachment.ts
Defines attachment commands, options, and output.
src/commands/attachment.test.ts
Tests command routing, output, and confirmation requirements.
… with marked
- Only remove the destination after a failed download when this download
created or opened it, so a response stream that fails before the file
opens never deletes a file that was already there. The response body is
wrapped as a Node stream only right before piping, so an early stream
error is not left unhandled.
- attachment list tokenizes the document with marked instead of a regex:
escaped and nested brackets in labels are read correctly and links in
inline or fenced code are ignored.
- Regression tests for both.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
A failed download can delete a pre-existing dangling symlink without --force because stat() misclassifies it as absent, allowing cleanup to unlink a destination the download never opened.
No open issues 🎉
1 previously missed issue
In code that hasn't changed since last review
Preserve dangling symlinks during failed download cleanup
src/lib/attachments.ts:373
A failed download can still delete a pre-existing dangling symlink without --force: stat() follows the link, reports ENOENT, and sets existedBefore to false. If the response stream fails before the destination reports EEXIST, cleanup then unlinks that symlink even though the download never opened it. Import and use lstat() here, treating only ENOENT as absence, and add a regression test with a dangling symlink and an immediately failing response body.
The reason will be displayed to describe this comment to others. Learn more.
Thanks for this, it's a well put together change. I ran type-check, lint:check, format:check, check:skill-sync and the tests locally (all green), and exercised upload and download end to end against a mock Outline server and a mock S3 server: the token stays on the instance, the upload goes out with a Content-Length, and a failed S3 upload deletes the registered attachment again.
A few things inline. The ones I'd like sorted before merging are the download output folder and the matching skill recipe, the file name fallback for S3 downloads, and the nested spinners during upload. The rest are nits.
- download: an --output ending in / is a folder and is created if missing;
a missing folder for a file path is reported as such instead of ENOENT/EISDIR.
- download: when the response has no Content-Disposition name, fall back to
the storage key in the served URL (S3 object path or files.get key)
before the attachment ID.
- download: strip control characters from server-supplied file names.
- download: cancel the redirect response body before following it.
- download: treat a dangling symlink as an existing file (lstat) so a failed
download never removes it.
- upload: the 'Uploading file...' spinner wraps only the transfer, so it no
longer nests with the attachments.create spinner.
- upload: failures from third-party storage read as 'Storage error: <status>
(<S3 Message>)' instead of an Outline API error.
- authorizedFetch: instance paths are appended to the base URL like
apiRequest, keeping a sub-path; it returns the URL and whether it was on
the instance.
- Use type aliases for the new shapes.
- Skill: download recipe uses one folder per attachment; note how list reads
links.
Thanks for the thorough review, @scottlovegrove. Everything is addressed in 87e6995, and I've replied in each thread. Copilot's follow-up on dangling symlinks is in the same commit: the pre-download check uses lstat, and only ENOENT counts as absent, with a regression test that fails against the old stat version.
Type-check, lint, format, skill sync and the tests (297) all pass. I also re-ran it against a live Outline 1.12 instance: upload, the per-attachment download recipe with two attachments that have the same name, and the missing-folder error.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Redirect resolution sends root-relative locations to incorrect destinations, and uncleared mock history causes an upload test to fail when run with the preceding failure test.
Root-relative Location headers are resolved against the URL that was
requested, so a storage redirect stays on the storage host and a sub-path
install does not double its prefix. The token is still scoped by origin in
authorizedFetch. Also clear the toApiError mock between tests.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed to evaluate unpublished findings, especially a critical download race that can delete another download’s file without ownership or force authorization.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an
ol attachmentcommand group (aliasattach) so files can be moved in and out of documents from the CLI:attachments.create, then sends it to the target Outline returns. It handles all three: Outline's ownfiles.create(local storage), a presigned S3 POST, and a presigned PUT (AWS_S3_UPLOAD_METHOD=put). If the transfer fails, the registered attachment is deleted again. It prints the Markdown link in the same form the editor writes (for images,[name bytes](…)for files).--appendadds that link to the end of the document.attachments.listonly returns the caller's own uploads, so it would miss files other people attached.--forceis passed, and removes partial files on failure.Implementation notes
api.ts: token resolution and the 401 refresh-and-retry move into shared helpers. The newauthorizedFetchuses them for non-JSON transfers. It only attaches the bearer token when the URL is on the instance's own origin, so the token never goes to S3.apiRequestbehaves as before, and its existing tests are unchanged.Blob, not aFormData. The bundled undicifetchfromhttp-dispatcher.tsdoes not accept Node's globalFormDataand sends it as the string[object FormData]; Outline then rejects it withbody: Invalid input: expected object, received string. ABlobbuilt from the file's lazyopenAsBlobhas a knownContent-Length(presigned S3 POSTs reject chunked bodies), and the file is never read into memory.attachments.redirectredirect by hand (redirect: 'manual'), which is what keeps the token on the instance.--appendsendsappend: truerather thaneditMode: 'append'. Every server with text edits understandsappend(newer ones map it toeditMode), whereas an older server would drop an unknowneditModeand replace the whole document with the link.SKILL.md(viasync:skill) and the README are updated.Testing
npm run type-check,lint:check,format:check,check:skill-syncandnpm testall pass. There are 284 tests, 28 of them new, covering upload (local, S3 POST, PUT, older servers withoutmode, cleanup on failure, missing file), download (manual redirect, directory output, overwrite refusal, errors, redirect loop),authorizedFetchtoken scoping and refresh, the link parser, multipart encoding, and the command surface.FILE_STORAGE=local, using an API key:cmp;This change was written with an AI coding assistant, then reviewed and tested as described above.