# 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](mailto:hello@known.info).

## 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](https://known.info/docs/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](https://known.info/docs/records) and [Schemas and retention](https://known.info/docs/schemas).

## 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](https://known.info/docs/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.