The known CLI

The known CLI lets you and your coding agents read and write Known from the terminal. The CLI is in early access. To try it, contact us.

Sign in

known login

known login opens your browser, where you sign in and select an organization. Each sign-in creates a session for one organization. To add another organization, run known login again.

Commands take the organization as their first argument:

known <org> <command> [arguments]

To see your sessions, run known sessions.

Set a project's organization

To skip the organization argument in a project, add a KNOWN_ORG file to the project's root directory:

echo acme > KNOWN_ORG
known wiki read general:handbook

Commands run in that directory or any directory below it use the organization in the file. The file contains no secrets, so you can commit it. To check which organization and account a command will use, run known ping.

If you use a coding agent in the project, tell it to run known ping before it writes.

Pages

Every path starts with its wiki's name. For example, general:handbook.onboarding is the page handbook.onboarding in the general wiki.

Command	Description
wiki wikis	List wikis, with their descriptions and access.
wiki tree <wiki>:[path]	Show the page tree.
wiki search <query> <wiki>:[path]	Search pages and records.
wiki read <wiki>:<path>	Print a page.
wiki write <wiki>:<path>	Write a whole page, from --text, --file, or standard input.
wiki edit <wiki>:<path>	Replace the text in --old with --new.
wiki move <wiki>:<from> <wiki>:<to>	Move or rename a page and the pages under it.
wiki history <wiki>:<path>	Show a page's revisions.
wiki changes <wiki>:	Show recent changes in a wiki.

Add --json to any command for machine-readable output.

Edit safely

To change part of a page, use wiki edit. It fails unless the text in --old appears exactly once, and it leaves the rest of the page unchanged.

To replace a whole page, read it with --json, note its revisionId, and pass it with --if-revision. If someone changed the page since you read it, the write fails. Read the page again, merge the changes, and retry. To see what changed, run wiki diff.

To link pages, use [[path]]. Before you move a page, run wiki links <wiki>:<path> to see what links to it. See Links.

Records

Command	Description
wiki records <wiki>:<path>	Read records.
wiki get <wiki>:<path>/<key>	Read one record.
wiki set <wiki>:<path>	Write a record. Use --if-version to update a row safely.
wiki del <wiki>:<path>/<key>	Delete a record.
wiki meta <wiki>:<path>	Set a page's key, schema, or retention.

For details, see Records and Schemas and retention.

Notes

To list a wiki's open notes, run wiki notes <wiki>:. After you update a page, resolve the note with wiki resolve <wiki>:<path> <id>. See Notes.

Errors

When a command fails because of a conflict, a missing page, or a permission, it prints a short message that says what to do next. When a session expires, the message includes the known login command to run.