Til

til

Capture and manage "Today I Learned" entries on OpenTIL -- from drafting to publishing, all within the CLI.

Setup

1. Go to https://opentil.ai/dashboard/settings/tokens and create a Personal Access Token with read:entries, write:entries, and delete:entries scopes
2. Copy the token (starts with til_)
3. Set the environment variable:

export OPENTIL_TOKEN="til_xxx"

Token Resolution

Token resolution order:

1. $OPENTIL_TOKEN environment variable (overrides all profiles)
2. ~/.til/credentials file — active profile's token (created by /til auth)

If neither is set, entries are saved locally to ~/.til/drafts/.

Credential File Format

~/.til/credentials stores named profiles in YAML:

active: personal
profiles:
  personal:
    token: til_abc...
    nickname: hong
    site_url: https://opentil.ai/@hong
    host: https://opentil.ai
  work:
    token: til_xyz...
    nickname: hong-corp
    site_url: https://opentil.ai/@hong-corp
    host: https://opentil.ai

• active: name of the currently active profile
• profiles: map of profile name → credentials
• Each profile stores: token, nickname (from API), site_url, host

Backward compatibility: If ~/.til/credentials contains a plain text token (old format), silently migrate it to a default profile in YAML format and write back.

Subcommand Routing

The first word after /til determines the action. Reserved words route to management subcommands; anything else is treated as content to capture.

Reserved words: list, publish, unpublish, edit, search, delete, status, sync, tags, categories, batch, auth.

Reference Loading

⚠️ DO NOT read reference files unless specified below. SKILL.md contains enough inline context for most operations.

On subcommand dispatch (load before execution):

On-demand (load only when the situation arises):

API Quick Reference

Create and publish an entry:

curl -X POST "https://opentil.ai/api/v1/entries" \
  -H "Authorization: Bearer $OPENTIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": {
      "title": "Go interfaces are satisfied implicitly",
      "content": "In Go, a type implements an interface...",
      "summary": "Go types implement interfaces implicitly by implementing their methods, with no explicit declaration needed.",
      "tag_names": ["go", "interfaces"],
      "published": true,
      "lang": "en"
    }
  }'

Key create parameters:

Management endpoints:

Full parameter list, response format, and error handling: see references/api.md

Execution Flow

Every /til invocation follows this flow:

1. Generate -- craft the TIL entry (title, body, summary, tags, lang)
2. Check token -- resolve token (env var → active profile in ~/.til/credentials)
   • If ~/.til/credentials exists in old plain-text format, migrate to YAML default profile first
   • Found -> POST to API with published: true -> show published URL
   • Not found -> save to ~/.til/drafts/ -> show first-run guide with connect prompt
   • 401 response -> save locally -> inline re-authentication (see Error Handling):
     • Token from ~/.til/credentials (active profile) or no prior token: prompt to reconnect via device flow → on success, update the active profile's token and auto-retry the original operation
     • Token from $OPENTIL_TOKEN env var: cannot auto-fix — guide user to update/unset the variable
3. Show identity -- when ≥2 profiles are configured, include Account: @nickname (profile_name) in result messages so the user always knows which account was used
4. Never lose content -- the entry is always persisted somewhere
5. On API failure -> save locally as draft (fallback unchanged)

/til <content> -- Explicit Capture

The user's input is raw material -- a seed, not the final entry. Generate a complete TIL from it:

• Short input (a sentence or phrase) -> expand into a full entry with context and examples
• Long input (a paragraph or more) -> refine and structure, but preserve the user's intent

Steps:

1. Treat the user's input as a seed -- craft a complete title + body from it
2. Generate a concise title (5-15 words) in the same language as the content
3. Write a self-contained Markdown body (see Content Guidelines below)
4. Generate a summary (see Summary Guidelines below)
5. Infer 1-3 lowercase tags from technical domain (e.g. rails, postgresql, go)
6. Detect language -> set lang (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, pt, ru, ar, bs, da, nb, pl, th, tr, it)
7. Follow Execution Flow above (check token -> POST or save locally)

No confirmation needed -- the user explicitly asked to capture. Execute directly.

/til -- Extract from Conversation

When /til is used without arguments, analyze the current conversation for learnable insights.

Steps:

1. Scan the conversation for knowledge worth preserving -- surprising facts, useful techniques, debugging breakthroughs, "aha" moments
2. Identify all TIL-worthy insights (not just one), up to 5
3. Branch based on count:

0 insights:

No clear TIL insights found in this conversation.

1 insight: Generate the full draft (title, body, tags), show it, ask for confirmation. On confirmation -> follow Execution Flow.

2+ insights: Show a numbered list (max 5), let the user choose:

Found 3 TIL-worthy insights:

  1. Go interfaces are satisfied implicitly
  2. PostgreSQL JSONB arrays don't support GIN @>
  3. CSS :has() enables parent selection

Which to capture? (1/2/3/all/none)

• Single number -> generate draft for that insight, show confirmation, proceed
• Comma-separated list (e.g. 1,3) -> generate drafts for selected, show all for confirmation, POST sequentially
• all -> generate drafts for each, show all for confirmation, POST sequentially
• none -> cancel

4. For each selected insight, generate a standalone TIL entry following Content Guidelines
5. Show the generated entry to the user and ask for confirmation before proceeding
6. On confirmation -> follow Execution Flow above (check token -> POST or save locally)

Auto-Detection

When working alongside a user, proactively detect moments worth capturing as TIL entries.

When to Suggest

Suggest when the conversation produces a genuine "aha" moment — something surprising, non-obvious, or worth remembering. Examples:

• Debugging uncovered a non-obvious root cause
• A language/framework behavior contradicted common assumptions
• Refactoring revealed a clearly superior pattern
• Performance optimization yielded measurable improvement
• An obscure but useful tool flag or API parameter was discovered
• Two technologies interacting produced unexpected behavior

Do NOT suggest for: standard tool usage, documented behavior, typo-caused bugs, or widely known best practices.

Rate Limiting

1. Once per session — after suggesting once (accepted or declined), never suggest again
2. Natural pauses only — suggest at resolution points or task boundaries, never mid-problem-solving
3. Respect rejection — if declined, move on without persuasion

Suggestion Format

Append at the end of your normal response. Never interrupt workflow.

Template:

💡 TIL: [concise title of the insight]
   Tags: [tag1, tag2] · Capture? (yes/no)

Example (at the end of a debugging response):

...so the fix is to close the channel before the goroutine exits.

💡 TIL: Unclosed Go channels in goroutines cause silent memory leaks
   Tags: go, concurrency · Capture? (yes/no)

Capture Flow

Auto-detected TILs bypass the extract flow. The suggestion itself is the candidate.

1. User replies yes / y / ok / sure → agent generates full entry (title, body, tags, lang) from the suggested insight → follows Execution Flow (POST or save locally)
2. User replies no / ignores / continues other topic → move on, do not ask again

Non-affirmative responses (continuing the conversation about something else) are treated as implicit decline.

Detailed trigger examples, state machine, and anti-patterns: see references/auto-detection.md

Management Subcommands

Management subcommands require a token. There is no local fallback -- management operations need the API.

/til list [drafts|published|all]

List entries. Default filter: drafts.

• API: GET /entries?status=<filter>&per_page=10
• Display as a compact table with short IDs (last 8 chars, prefixed with ...)
• Show pagination info at the bottom

/til publish [<id> | last]

Publish a draft entry.

• last resolves to the most recently created entry in this session (tracked via last_created_entry_id set on every successful POST)
• Fetch the entry first, show title/tags, ask for confirmation
• On success, display the published URL
• If already published, show informational message (not an error)

/til unpublish <id>

Revert a published entry to draft.

• Fetch the entry first, confirm before unpublishing
• If already a draft, show informational message

/til edit <id> [instructions]

AI-assisted editing of an existing entry.

• Fetch the full entry via GET /entries/:id
• Apply changes based on instructions (or ask what to change if none given)
• Show a diff preview of proposed changes
• On confirmation, PATCH /entries/:id with only the changed fields

/til search <keyword>

Search entries by title.

• API: GET /entries?q=<keyword>&per_page=10
• Same compact table format as list

/til delete <id>

Permanently delete an entry.

• Fetch the entry, show title and status
• Double-confirm: "This cannot be undone. Type 'delete' to confirm."
• On confirmation, DELETE /entries/:id

/til status

Show site status and connection info. Works without a token (degraded display).

• With token: GET /site -> show username, entry breakdown (total/published/drafts), token status, local draft count, dashboard link
• Without token: show "not connected", local draft count, setup link

/til sync

Explicitly sync local drafts from ~/.til/drafts/ to OpenTIL. Requires token.

• List pending drafts, POST each one, delete local file on success
• Show summary with success/failure per draft

/til tags

List site tags sorted by usage count (top 20). Requires token.

• API: GET /tags?sort=popular&per_page=20&with_entries=true
• Show as compact table with tag name and entry count

/til categories

List site categories. Requires token.

• API: GET /categories
• Show as compact table with name, entry count, and description

/til batch <topics>

Batch-capture multiple TIL entries in one invocation. Requires explicit topic list.

• User lists topics separated by newlines, semicolons, or markdown list items (- / 1.)
• Generate a draft for each -> show all drafts for confirmation -> POST sequentially
• On partial failure, show per-entry success/failure (same format as /til sync)

ID Resolution

• In listings, show IDs in short form: ... + last 8 characters
• Accept both short and full IDs as input
• Resolve short IDs by suffix match against the current listing
• If ambiguous (multiple matches), ask for clarification

Session State

Track the following session state (not persisted across sessions):

• last_created_entry_id -- set on every successful POST /entries (201). Used by /til publish last.
• active_profile -- the profile name resolved at first token access. Reflects the active field from ~/.til/credentials (or $OPENTIL_TOKEN override). Used for identity display and draft attribution.

Detailed subcommand flows, display formats, and error handling: see references/management.md

Agent Identity

Three layers of attribution signal distinguish human-initiated from agent-initiated TILs.

Layer 1: HTTP Headers

Include these headers on every API call:

X-OpenTIL-Source: human | agent
X-OpenTIL-Agent: <your agent display name>
X-OpenTIL-Model: <human-readable model name>

• Source: /til <content> and /til -> human; Auto-detected -> agent
• Agent: use your tool's display name (e.g. Claude Code, Cursor, GitHub Copilot). Do not use a slug.
• Model: use a human-readable model name (e.g. Claude Opus 4.6, GPT-4o, Gemini 2.5 Pro). Do not use a model ID.
• Agent and Model are optional -- omit them if you are unsure.