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"

1. $OPENTIL_TOKEN

   environment variable

2. ~/.til/credentials

   file (created by

   /til auth

   )

~/.til/drafts/

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...",
      "tag_names": ["go", "interfaces"],
      "published": true,
      "lang": "en"
    }
  }'

content

title

tag_names

["go", "concurrency"]

published

false

true

lang

en

zh-CN

zh-TW

ja

ko

slug

visibility

public

unlisted

private

/entries?status=draft&q=keyword

/entries/:id

/entries/:id

/entries/:id

/entries/:id/publish

/entries/:id/unpublish

/site

/tags?sort=popular

/categories

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

/til

1. Generate -- craft the TIL entry (title, body, tags, lang)
2. Check token -- resolve token (env var →

   ~/.til/credentials

   )
   • Found -> POST to API with

     published: true

     -> show published URL
   • Not found -> save to

     ~/.til/drafts/

     -> show first-run setup guide
3. Never lose content -- the entry is always persisted somewhere
4. On API failure -> save locally as draft (fallback unchanged)

• 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

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. Infer 1-3 lowercase tags from technical domain (e.g.

   rails

   ,

   postgresql

   ,

   go

   )
5. 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

   )
6. Follow Execution Flow above (check token -> POST or save locally)

/til

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:

No clear TIL insights found in this conversation.

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

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

• 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

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

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

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

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

• 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)

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

• 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

• API:

  GET /entries?q=<keyword>&per_page=10

• Same compact table format as

  list

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

  DELETE /entries/:id

• 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/drafts/

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

• API:

  GET /tags?sort=popular&per_page=20&with_entries=true

• Show as compact table with tag name and entry count

• API:

  GET /categories

• Show as compact table with name, entry count, and description

• 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

  )

• 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

last_created_entry_id

POST /entries

/til publish last

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

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.

• Auto-detected TILs: automatically add

  agent-assisted

  to the tag list

• /til <content>

  and

  /til

  : do not add the tag (unless the Agent substantially rewrote the content)

source

• Public page: shows

  ✨ via {agent_name}

  , or

  ✨ AI

  when agent_name is absent
• Tooltip (hover): shows

  {agent_name} · {model}

  when both are present
• Dashboard: shows ✨ badge + agent_name, or "Agent" when agent_name is absent

• Self-contained: The reader must understand the entry without any conversation context. Never write "as we discussed", "the above error", "this project's config", etc.
• Desensitized: Remove project names, company details, colleague names, internal URLs, and proprietary business logic. Generalize specifics: "our User model" -> "a model", "the production server" -> "a production environment", "the Acme payment service" -> "a payment gateway".
• Universally valuable: Write to StackOverflow-answer standards. A stranger searching for this topic should find the entry immediately useful. Content only useful to the author belongs in private notes, not TIL.
• Factual tone: State facts, show examples, explain why. Avoid first-person narrative ("I was debugging...", "I discovered..."). Exception: brief situational context is fine ("When upgrading Rails from 7.2 to 8.0...").
• One insight per entry: Each TIL teaches exactly ONE thing. If there are multiple insights, create separate entries.
• Concrete examples: Include code snippets, commands, or specific data whenever relevant. Avoid vague descriptions.
• Title: 5-15 words. Descriptive, same language as content. No "TIL:" prefix.
• Content: Use the most efficient format for the knowledge — tables for comparisons, code blocks for examples, lists for enumerations, math (

  $inline$

  /

  $$display$$

  ) for formulas with fractions/subscripts/superscripts/greek letters, Mermaid diagrams (

  ```mermaid

  ) for flows/states/sequences that text cannot clearly express. Simple expressions like

  O(n)

  stay as inline code; use math only when notation complexity warrants it. Only use prose when explaining causation or context. Never pad content; if one sentence suffices, don't write a paragraph.
• Tags: 1-3 lowercase tags from the technical domain (

  go

  ,

  rails

  ,

  postgresql

  ,

  css

  ,

  linux

  ). No generic tags like

  programming

  or

  til

  .
• Lang: Detect from content. Chinese ->

  zh-CN

  , Traditional Chinese ->

  zh-TW

  , English ->

  en

  , Japanese ->

  ja

  , Korean ->

  ko

  .
• Category: Do not auto-infer

  category_name

  -- only include it if the user explicitly specifies a category/topic.

TIL captured (saved locally -- token expired)

  File: ~/.til/drafts/20260210-143022-go-interfaces.md

Token expired. Run /til auth to reconnect.

TIL captured (saved locally -- API unavailable)

  File: ~/.til/drafts/20260210-143022-go-interfaces.md

Full error codes, 422 auto-fix logic, and rate limit details: see references/api.md

~/.til/drafts/

YYYYMMDD-HHMMSS-<slug>.md

---
title: "Go interfaces are satisfied implicitly"
tags: [go, interfaces]
lang: en
---

In Go, a type implements an interface...

Full directory structure, metadata fields, and sync protocol: see references/local-drafts.md

• Entries are published immediately by default (

  published: true

  ) -- use

  /til unpublish <id>

  to revert to draft
• The API auto-generates a URL slug from the title
• Tags are created automatically if they don't exist on the site
• Content is rendered to HTML server-side (GFM Markdown with syntax highlighting, KaTeX math, and Mermaid diagrams)
• Management subcommands (

  list

  ,

  publish

  ,

  edit

  ,

  search

  ,

  delete

  ,

  tags

  ,

  categories

  ,

  sync

  ,

  batch

  ) require a token -- no local fallback. Exception:

  status

  and

  auth

  work without a token.
• Scope errors map to specific scopes:

  list

  /

  search

  /

  tags

  /

  categories

  need

  read:entries

  ,

  publish

  /

  unpublish

  /

  edit

  /

  sync

  /

  batch

  need

  write:entries

  ,

  delete

  needs

  delete:entries

  .

  status

  uses

  read:entries

  when available but works without a token.