Ork CLI

Write, search, and manage your Ork notes from the terminal.

ork is a thin, fast command-line client for Ork. It speaks to the same API as the web and mobile apps, authenticates with your account, and reads & writes notes as plain Markdown.

Contents

• Install
• Quick start
• Configuration
• Authentication
• Command reference
  • Auth · Notes · Tags · Collections · API keys
• Markdown support
• Scripting & JSON output
• Troubleshooting

Install

npm install -g @ork.so/ork-cli      # provides the `ork` binary
# or run without installing:
npx @ork.so/ork-cli --help

From source

# from the monorepo root (Node >= 22)
pnpm --filter @ork.so/ork-cli build

# put `ork` on your PATH (pick one):
pnpm --filter @ork.so/ork-cli exec pnpm link --global
# …or symlink the built binary into a dir on your PATH:
ln -sf "$PWD/apps/cli/dist/index.js" /opt/homebrew/bin/ork

Verify:

ork --version
ork --help

Quick start

ork login                       # sign in via magic link
ork new -t "First note" -m "Hello from the **terminal**."
ork ls                          # list recent notes
ork search "terminal"           # full-text search
ork view <id>                   # print a note as Markdown

Configuration

The CLI is configured entirely through environment variables and a small config file. No config command needed.

Token storage — after ork login, your session token is written to:

~/.config/ork/config.json     # mode 0600

It holds { token, expiresAt, user }. Delete it (or run ork logout) to sign out.

Authentication

Ork uses magic-link sign-in. Your session lasts 30 days on a sliding window — any use within 30 days refreshes it, so active users effectively stay signed in.

ork login

ork login
# ? Email: you@example.com
# ✓ Magic link sent. Paste the magic link or token:
#   <paste the link from your email, or just the token in it>
# ✓ Signed in as you@example.com

Flags:

ork logout

Revokes the session server-side and removes the local token.

ork whoami

ork whoami
# you@example.com (@you)
# session expires 7/27/2026, 12:00:00 PM
ork whoami --json

🔑 For agents / automation, use an API key instead of a session — see API keys. Keys are revocable and don’t expire.

Command reference

Run ork <command> --help for any command. Global: every command exits non-zero on error and prints ✗ <message>.

Notes

ork new — create a note

Body comes from (in priority order): -m, -f, piped stdin, or $EDITOR.

# inline markdown
ork new -t "Standup" -m "- shipped X
- [ ] review PR"

# from a file
ork new -t "Spec" -f ./spec.md

# from stdin
echo "# Quick idea" | ork new -t "Idea"

# open your editor (no other input given, in a TTY)
ork new

# with tags (created if they don't exist)
ork new -t "Research" -m "..." -T ml -T papers

ork ls — list notes

ork ls               # 20 most recent
ork ls -n 50         # limit
ork ls --pinned      # only pinned
ork ls --json

ork search <query>

ork search "postgres encryption"
ork search kubernetes --json

ork view <id>

Renders the note’s blocks back to Markdown.

ork view a8f3kd2
ork view a8f3kd2 --json     # full note + blocks

ork edit <id>

Opens the note’s current Markdown in $EDITOR; saving replaces the body.

⚠️ edit is a full-body replace — it rewrites the note from your Markdown. Media/URL blocks that Markdown can’t express are not preserved.

ork rm <id>

ork rm a8f3kd2          # asks to confirm
ork rm a8f3kd2 -y       # skip confirmation

Publish & pin

ork publish a8f3kd2     # prints the public URL
ork unpublish a8f3kd2
ork pin a8f3kd2
ork unpin a8f3kd2

Tags

ork tag ls
ork tag new "Important" -i ⭐ -c "#ef4444"   # icon + hex color
ork tag add <noteId> work followup           # attach (auto-creates)
ork tag remove <noteId> <tagId>              # detach from a note
ork tag rm <tagId>                           # delete the tag entirely

Collections

col is an alias for collection.

ork col ls
ork col new "Launch" -d "launch notes"
ork col add <colId> <noteId> [<noteId2> ...]
ork col remove <colId> <noteId>
ork col publish <colId> --slug my-launch     # a collection needs a slug to publish
ork col unpublish <colId>
ork col rm <colId>

ℹ️ Unlike notes, a collection’s slug isn’t auto-generated — pass --slug the first time you publish.

API keys

Scoped, revocable, non-expiring keys for headless use — the MCP server, agents, and CI. Minted on your signed-in session; the key is shown once.

ork token create "Claude agent"      # prints the key once — copy it
ork token create "ci" -e 2592000     # optional expiry in seconds
ork token ls
ork token revoke <keyId>

Use the key as ORK_API_KEY (see the MCP docs):

ORK_API_KEY=ork_… ork-mcp

Markdown support

ork new / ork edit convert Markdown to Ork blocks (and back on view):

Block-level HTML (<h2>…</h2>, <p>, <ul>) is also accepted and converted to the right blocks. For full fidelity you can bypass Markdown entirely with --raw and pass a JSON block array.

Scripting & JSON output

Most read/create commands accept --json for machine-readable output, and every command sets a non-zero exit code on failure.

# capture a new note's id
id=$(ork new -t "x" -m "y" --json | jq -r '.note.id')

# pipe content in
cat report.md | ork new -t "Weekly report"

For non-interactive auth (CI), set a token directly or via env:

ORK_TOKEN=… ork ls                  # session token
# or, preferred for automation:
ORK_API_KEY=… ork ls                # scoped API key (x-api-key)

Troubleshooting

_{See also: Ork MCP Server — the same capabilities exposed to AI agents.}