CLI and API keys

Account and server required

The CLI connects to the server API. It does not read projects that exist only in another browser’s local workspace.

For the complete agent setup, start with connect your agent. The CLI also works directly from a terminal or another agent.

Install and connect the CLI

Use a current Node.js LTS version (the CLI requires Node 18 or newer):

npm install -g tylor-cli@latest
tylor login

With CLI 0.4.0 or newer, login opens Tylor in your default browser. If you are already signed in, you go straight to the approval screen; otherwise sign in with email/password, Google, or GitHub first.

1. Check the signed-in account and the device name.
2. Match the eight-character code against the one in your terminal.
3. Select I started this login and the code matches my terminal, then Connect CLI.
4. Return to the terminal and wait for Connected as… and Saved login to….
5. Run tylor tree or tylor list to check access.

The screenshot uses a temporary example account and code. Only approve a request you started; never approve a login link sent by someone else. The new key acts as your account, including reading, changing and deleting data you can access. Choose Decline if anything looks wrong. Use a different account signs out so you can select the intended account before approving.

The CLI saves the key and server URL in ~/.config/tylor/config.json, preserving other settings. On macOS/Linux the file is written with owner-only permissions (600). Windows uses your user profile; protect that profile with its normal account permissions. The key is never printed or placed in the browser URL. Each device key can be revoked in Account → Advanced → API keys.

Browser does not open, or the CLI runs remotely

tylor login --no-browser

Open the printed link in a browser where you can sign in to Tylor, even on another device. Match the code and approve. The login is saved on the machine running the CLI. Requests expire after ten minutes; if interrupted, run tylor login again. The CLI retries temporary network failures and attempts to cancel an unfinished login when you press Ctrl+C.

The first account-dependent command in an interactive terminal offers browser setup if no key is configured. Scripts never prompt automatically: run tylor login separately or supply a key through TYLOR_API_KEY in your automation environment.

Reconnect an account or use another server

With CLI 0.6.0+, tylor login adds the account approved in the browser while keeping other logins. If that account on that server is already saved, use tylor login --replace to reconnect it. The browser still requires approval. Its alias, default and backup settings are retained. Previous keys remain active until revoked in Tylor; other clients may still use them.

For a self-hosted instance, specify both endpoints:

tylor login --api-url https://api.example.org --web-url https://tylor.example.org

Use the website’s origin for --web-url, without a path. That website must be configured to use the same API, and the backend must allow its origin. HTTPS is required except for localhost development. Login remembers both URLs. Use --name "Office Mac" to label the device key.

TYLOR_API_KEY and TYLOR_API_URL are environment overrides. Unset TYLOR_API_KEY before browser login. The CLI refuses to send a saved login key to a different API URL; log in to that server explicitly instead. Existing manually configured keys remain supported.

Manual API keys for automation

Open Account → Advanced → API keys, create a named key, and copy it when shown. Creating a key requires your signed-in browser session. An existing API key cannot create another key. CLI login also requires explicit browser approval; existing keys continue to work for automation and can be revoked individually. Set TYLOR_API_KEY privately in your automation environment. Legacy single-key configurations with an apiKey field remain supported and migrate on use; do not add a top-level key to an already migrated multi-account config. Preserve existing settings and restrict the file to your user (chmod 600 ~/.config/tylor/config.json on macOS/Linux). For a non-default instance, also set TYLOR_API_URL or save apiUrl alongside the key.

Keep credentials out of documents, screenshots, Git and chat messages. Revoke keys that are no longer needed or may have been exposed. The default API is https://api.tylor.app. The CLI cannot access projects stored only in another browser’s local workspace.

For EBADENGINE, EACCES, missing commands or login errors, see CLI troubleshooting. See the CLI reference for all commands.

Use personal and company accounts

CLI 0.6.0 or newer keeps multiple logins. Run login once for each account, approving the intended identity in your browser. Adding another account keeps your existing default.

tylor login --alias personal
tylor login --alias company
tylor auth list
tylor --account company auth status
tylor --account company create "Quarterly report"
tylor --account personal create "Personal notes"

Email addresses work directly: tylor --account company@example.com tree. Put --account before the command. Aliases are optional; add or rename one with tylor auth alias company@example.com company. They use 1–40 lowercase letters, digits, underscores or hyphens and start with a letter (legacy is reserved).

tylor auth list --json lists saved emails, aliases, account IDs, server URLs and the default, without keys. tylor --account company auth status --json verifies the actual identity online. If the same email exists on two servers, use a unique alias or the ID from the list. An email change requires reconnecting with tylor login --replace to refresh saved identity. Listing saved accounts does not prove their keys are still valid.

For everyday terminal use, choose a default with tylor auth default personal. An explicit --account applies only to that command. A command keeps the same account for every request, even if another terminal changes the default while it runs. Agents should pass --account on every command for a task, so separate conversations can work in separate accounts.

Tell your agent: “Use company@example.com for this report.” Refresh the installed Tylor skill after upgrading so the agent knows this workflow.

An explicit account conflicts with TYLOR_API_KEY; unset that override to use saved accounts. A conflicting TYLOR_API_URL is also refused. Missing, ambiguous or revoked accounts never fall back to another login. Without --account, an environment key retains precedence over the saved default. The CLI never changes your browser’s signed-in account when running commands.

Existing logins and local work

The old single-login configuration is migrated automatically, retaining its key, server, default and backup settings. tylor auth list verifies its email when reachable. An unavailable legacy key remains listed without an identity; reconnect or add another account with tylor login and set your intended default. Credentials stay in the private local config, never in checkouts.

New project checkouts are bound to the authenticated account and server, including shared projects. Use separate directories for personal and company work. A checkout pulled before 0.6.0 has no account binding: preserve local edits, pull into a fresh directory, and merge your intended changes. If it contains an uncertain pending write, keep its receipt and recover with CLI 0.5.0 and the original credential before migrating; never delete the receipt or change its account to retry. Reference-library sidecars already check account ownership.

Git library backups have separate settings and directories per account. Existing backup settings stay with the old login; initialize backups for a new account separately. See library backups for commands.

Browse folders and projects

With CLI 0.3.0 or newer, use tree for a workspace overview:

tylor tree
tylor tree --ids
tylor tree <folderId> --depth 2
tylor tree --json

Tylor
├── School/
│   ├── Lessons/
│   │   └── Introduction [template]
│   └── Exam
└── Notes [shared]

2 folders, 3 projects

Folders appear first and end in /. Shared items and templates are labeled. Use --ids to get the full IDs needed by commands such as pull, mv and create workflows. Pass a folder ID to focus on that subtree. Items whose parent folder you cannot access appear at the root. The tree includes accessible projects and package source projects, but excludes Trash. It reads server metadata and does not download document files, packages or fonts.

--depth 2 shows two levels below the workspace or selected folder; --depth 0 shows only the root. Without this option, all levels appear. Hidden children are marked explicitly. The footer counts all descendants of the selected root and reports how many the limit hides.

For agents and scripts, --json returns a structured tree with full IDs, node types, sharing/role metadata, and a summary. Start with tylor tree --json --depth 2, then use tylor tree <folderId> --json to expand a relevant folder. A node’s truncated: true means its children are hidden by the depth limit, not absent. Use IDs for subsequent actions because names can repeat. Refresh the tree after reorganizing folders or changing sharing.

Configure library backups

Use tylor sync to back up your account’s packages and fonts to Git. Its sync.repo, sync.dir, and sync.branch settings live inside the selected account entry in ~/.config/tylor/config.json. See library backups with the CLI for configuration examples, initialization, push, restore, and troubleshooting.

Use automation with an open editor

External tools work with saved server files. Wait for browser edits to sync before asking a tool to modify the same project. When returning to the editor, follow any update or reload message and check the resulting document.

Keep a history checkpoint or backup before broad automated edits. Verify the final source and PDF, even if an agent reports that compilation succeeded.

Watch CLI activity live

Open Account → Advanced → API activity… to follow CLI and integration requests. The panel stays beside your workspace on desktop and fills the screen on mobile. Expand it for more space, or leave it docked while you edit.

The Console view reads like a terminal: older requests are above newer ones. Each entry shows its time, status, source, HTTP method, route and duration, with its action, project when available, and API key name below. Colors and labels distinguish OK, ERROR, RUN (running), and STOP (interrupted). Running entries update in place when they finish. Select a line for request details, the full request ID, and guidance for failures.

The console follows new activity automatically. Scroll up to read without being pulled back to the bottom; Jump to latest resumes following. Pause stops updates, while Go live catches up with saved requests. Expand the panel for a denser, wider console.

Open Filters for search and the project, API key, source and outcome filters. Requests switches to the original card view, with newest requests first. Each page contains up to 100 requests; Older and Newer, when available, browse saved history. Summary counts cover all matching retained requests, not just the current page.

Copy or export diagnostics

• Copy log copies the visible console lines as plain text.
• Export .log downloads those same lines for an administrator or a support report.
• Clear view hides current console lines locally. Show cleared brings them back; saved history and the Requests view are unaffected. Closing the panel resets this local view.

Copy and export respect the selected page, filters, and cleared lines. They do not export the entire seven-day history. Pause first if you want to inspect a stable set before copying. Exports use full UTC timestamps and request IDs, and include the method, route template, status, duration, action, API key name and project metadata when available. The console shows times in your browser’s local timezone. Credentials and request/response bodies are excluded. If clipboard access is unavailable, use Export .log instead.

This remains your account’s activity, including when an administrator opens it. It is not a platform-wide console. Check project and key names before sharing a diagnostic log.

History covers the last seven days, up to 10,000 requests per account. It records request metadata, without document contents or credentials. Only requests made with a verified API key are included; requests that never reached Tylor or used invalid/revoked keys do not appear. Older CLI versions appear under Integrations until updated.

Interrupted means Tylor could not record a completed response. The operation may have taken effect, so check your project or CLI output before retrying.

The key’s copy button confirms success only after the clipboard accepts the key. If copying fails, select the full key shown in the dialog and copy it manually before closing; the secret is shown only once.

Your bibliography

Use tylor library pull references.bib to create a local library checkout, library import for an existing file, and library push to preview local changes. Add --apply only after reviewing the selection. tylor library doi <DOI> --json retrieves metadata without saving it. See Your reference library for replacement selection, sidecars, conflicts, offline editing and retry instructions.

Private speaker notes

CLI 0.7.0 adds author-private notes. Upgrade with npm install -g tylor-cli@latest and refresh copied agent instructions with tylor skill install ~/.codex/skills (or your agent’s skills folder).

tylor --account <account> notes list <projectId> --json
tylor --account <account> notes set <projectId> --main main.typ --page 2 --from note.txt --expected-version none
tylor --account <account> notes set <projectId> --view <viewId> --from note.txt --expected-version <version>
tylor --account <account> notes export <projectId> --format markdown --out private-notes.md
tylor --account <account> notes export <projectId> --format json --out private-notes.json
tylor --account <account> notes export <projectId> --format html --out private-handout.html

The first write creates a page draft. In the browser, inspect the intended slide and choose Present → Review prepared notes → Use on this page; changing a draft later requires adopting it again. For existing notes, take the full viewId and version from list --json. Never replace a newer version blindly after a conflict. Empty input clears text while retaining a version for conflict protection. --from - reads stdin; notes are limited to 10,000 characters.

If the write outcome is uncertain, keep the input unchanged and repeat with the error’s --request-id, original expected version and same account. Exports contain your saved server notes only: unsynced browser edits and local recovery copies are not included. --out refuses existing files; without it, private content goes to stdout. HTML is a printable notes-only handout; JSON is an export, with no automatic import. Ordinary document exports exclude private notes. See Preparing and exporting notes.

After CLI edits, use Notes options → Reload notes in an already-open browser notes panel to fetch the saved changes.

PDF with private speaker notes (CLI 0.7.1+)

tylor export <projectId> private-talk.pdf --speaker-notes

Compiles saved server files and appends only the authenticated user’s saved notes, including labelled drafts and captured revisions. These may not match the current slides; review before sharing. The private output must be a new file and is created with owner-only permissions. You can combine --comments and --speaker-notes. Ordinary exports and public links exclude private notes. Push local source changes and save note edits before exporting. No saved notes returns an error; notes-only Markdown/JSON/HTML exports remain available with tylor notes export.

Annotated sessions (CLI 0.7.1+)

tylor session export <projectId> annotated.pdf --drawings drawings.json
tylor session save <projectId> annotated.pdf --name "Research talk"
tylor session list <projectId>
tylor session download <projectId> <sessionId> saved-talk.pdf
tylor session delete <projectId> <sessionId>

Example drawings.json (page numbers start at 1; coordinates run from 0 to 1, from the page’s top-left):

{"schemaVersion":1,"pages":[{"page":1,"strokes":[{"colour":"#e11d48","points":[[0.2,0.6],[0.8,0.6]]}]}]}

Export compiles saved server source once and overlays vector strokes, retaining every page and selectable document text. Push changes first and verify page placement in the PDF. Colours are #e11d48, #0284c7, #15803d, #18181b; stroke width is 2 pt. Each stroke has 2–2,000 points; there are at most 250 strokes per annotated page and 100,000 points in total. No private notes are included. Use --speaker-notes on ordinary tylor export for the separate notes appendix.

Saved PDFs are private to the caller and immutable. Saving the same file/name retries under a stable ID; changing the bytes or name creates a new session. Downloads/exports require a fresh output path and use 0600 permissions. Saved PDFs are limited to 32 MB and count against the saving author’s quota. Listing requires current project membership; trash hides them and purge removes them. They are excluded from project ZIPs, Git, copies, public links and project archives. Never save a PDF containing private notes as though it were a notes-free audience artifact.

Browser drawings become accessible here only after Export session → Save session to my account has synced. Download annotated session PDF alone does not upload a copy. Sessions are final PDFs, not drawing replays or editable slide sources. session save can also store a PDF already downloaded from the browser. Do not delete saved sessions without an explicit request.

Saved sessions are limited to 1,000 per author per project; delete earlier sessions to free a slot.

Local file and credential safeguards

Bulk tylor create and tylor push skip common credential files such as .env*, private keys, .npmrc, .ssh, .aws and service-account JSON. Review skipped paths; use --include-sensitive-files only when you deliberately intend to upload them. This filename check cannot detect every secret inside an ordinary document. tylor put uploads the individual file you explicitly select.

tylor render prints a path inside a private random temporary directory. Delete that directory after your review. An explicit --out must be a new file; it cannot be combined with --all.