iA Writer supports a variety of commands to open, create, read, and write files.
Summary
Overview
Commands can be set to iA Writer by constructing special URLs:
ia-writer://command?parameter1=value1¶meter2=value2
x-callback-url
All commands can support x-callback-url:
ia-writer://x-callback-url/command?x-parameter1=x-value1¶meter1=value1¶meter2=value2
Some commands will return parameters on x-success
.
Auth
For privacy and security, commands that modify or return data using x-callback-url require auth-token
parameter. Auth token is synced across all your devices using iCloud. Auth token can be found in:
- On Mac: iA Writer → Preferences → General → URL Commands → Manage.
- On iOS: Library → Settings → URL Commands.
Data Types
- String
- Percent encoded. 4,000 or fewer characters before encoding.
- Path
- Percent encoded.
/
refers to the default location (iCloud or local)./Locations/From Other Apps/
is available on iOS./Locations/Name/
can be used to filter files from custom locations on macOS.- Use contextual menu in Library and Organizer to copy paths on macOS.
- Tap and hold items in Library to copy paths on iOS.
- Boolean
- Either
true
orfalse
.
Interface Commands
Open a screen in iA Writer.
open
command
Opens Editor with an existing document.
Parameters
path
- Path. Required. Path to file.
edit
- Boolean. Optional. If true, keyboard will be shown on iOS devices.
Return parameters on x-success
None.
new
command
Opens Editor with a new document.
Parameters
path
- Path. Optional. Path for the file to be created. If omitted the file will be created at the root of the default location. If the path points to a directory, the file will be automatically named. If the path points to a file, it must have a plain text file extension, or the path will be ignored. The proposed filename will be used, but adjusted to avoid overwriting an existing file.
text
- String. Optional. File contents.
edit
- Boolean. Optional. If true, keyboard will be shown on iOS devices.
Return parameters on x-success
None.
quick-search
command
Opens Quick Search with a given query.
Parameters
query
- String. Optional.
Return parameters on x-success
None.
Data Commands
Silenty read and write data.
read
command
Reads and returns files contents.
Parameters
auth-token
- String. Required.
path
- Path. Required. Path to the file to read.
Return parameters on x-success
path
- Path. Path to the file.
text
- String. File text.
write
command
Creates or modifies an existing file and returns file contents.
Parameters
auth-token
- String. Required.
path
- Path. Required.
text
- String. Optional.
mode
- String. Optional.
create
Default. Adjusts last path component to avoid replacing an existing file.replace
Replaces an existing file.append
Appends the given text to an existing file.append-location
- String. Optional. Used only when
mode
isappend
. beginning
Append text at the beginning of a file.end
Default. Append text at the end of a file.append-padding
- Boolean. Optional. Default:
true
. Make a paragraph out of appended text. Used only whenmode
isappend
.
Return parameters on x-success
path
- Path. Path to the file that was created or modified.
text
- String. File contents after writing.
version
command
Returns iA Writer app version and URL scheme version.
Parameters
None.
Return parameters on x-success
scheme-version
- String. URL scheme version.
app-version
- String. App version.
Version History
- 1
- Initial release.
- 2
- Fixed
write
command parameterappend-padding
. It was inverted in version 1. It was inverted in version 1: padding was appended withfalse
, and not appended withtrue
.