Skip to content
Metakip Docs

Metakip CLI: Install And Manage Pages

The Metakip CLI lets you use Metakip from a terminal. The browser and CLI use the same content layer, so a page created or edited by the CLI appears in the browser.

Before You Begin

Section titled “Before You Begin”

You need a Metakip account and a named API token from Metakip Settings → API tokens. The token is shown only when it is created. Keep it private.

Install The CLI

Section titled “Install The CLI”

On Linux and macOS:

Terminal window
curl -fsSL https://metakip.com/install.sh | sh

On Windows PowerShell:

Terminal window
irm https://metakip.com/install.ps1 | iex

The installer adds the CLI directory to your shell profile, but profile changes apply only to future sessions. Open a new terminal, or reload the appropriate profile (source ~/.bashrc, source ~/.zshrc, or . $PROFILE in PowerShell), before invoking metakip by name.

Check the installation:

Terminal window
metakip --version

You should see the installed CLI version. If the command is not found, open a new terminal or reload the profile that the installer changed.

Sign In To Metakip

Section titled “Sign In To Metakip”

Create a named token in Metakip Settings → API tokens, then run:

Terminal window
metakip login

For a self-hosted server:

Terminal window
metakip login --url https://your-metakip.example.com

Check the connection without printing the token:

Terminal window
metakip whoami
metakip doctor

Read Pages

Section titled “Read Pages”
Terminal window
metakip page search "project notes"
metakip page list
metakip page view "Page Title"
metakip --json page search "project notes"
metakip --json page list
metakip --json page view PAGE_ID

page search searches page titles only and returns at most 20 matching pages, including their folder paths. Use a returned page ID with page view or another page command. Use page IDs in scripts; titles are convenient for interactive use but can be ambiguous.

Create And Edit Pages

Section titled “Create And Edit Pages”
Terminal window
metakip page create --title "Research Notes" --content-file notes.md

For a small, targeted change:

Terminal window
metakip page edit exact PAGE_ID \
  --old-text "The old exact passage." \
  --new-text "The revised passage."

Read the page immediately before editing. The CLI refuses to guess if the passage is missing, repeated, or changed.

Import And Export

Section titled “Import And Export”
Terminal window
metakip import page notes.md
metakip import folder ./notes
metakip upload image ./diagram.png --page PAGE_ID --alt "System diagram"
metakip export page PAGE_ID --output page.md
metakip export all --output metakip-export.zip

The upload command prints a managed Markdown image reference. Insert that reference with a targeted page edit. If the image is already reliably hosted for every intended reader, you can instead add ![Diagram](https://example.com/diagram.png) directly. Avoid base64 data images because they bloat the collaborative page document. Private managed image URLs require access to a referenced page. API clients can download them with an API token that has pages:read; the CLI’s upload permission alone does not grant read access.

Share Pages And Folders

Section titled “Share Pages And Folders”

Use a token with write access to manage direct grants, invitations, public-link access, and inherited permissions. Resolve a page by title or a folder by name, or use its UUID:

Terminal window
metakip share page show "Project notes"
metakip share folder add "Research" colleague@example.com --permission edit
metakip share page update "Project notes" colleague@example.com --permission view
metakip share folder remove "Research" colleague@example.com --yes
metakip share page leave "Project notes" --yes
metakip share folder resend "Research" invitee@example.com
metakip share page cancel "Project notes" invitee@example.com --yes
metakip share page inherit PAGE_ID off
metakip share page link PAGE_ID --permission view --yes
metakip share workspace show
metakip share workspace add colleague@example.com --role editor
metakip share workspace update colleague@example.com --role viewer
metakip share workspace remove colleague@example.com --yes
metakip share workspace leave JOINED_WORKSPACE_OWNER_ID --yes

share page add and share folder add grant access directly when possible, or send an invitation when the recipient needs to join first. Use the same resource and email with update or remove for a direct share, and with resend or cancel for a pending invitation. Workspace member and invitation commands also identify people by email.

For owners and administrators, share page show and share folder show list direct shares and pending invitations by email. Other viewers receive a limited summary without hidden settings. JSON output retains internal share and invitation IDs, but the CLI commands use email to identify the person. Use share page leave or share folder leave to remove an item shared with you from your own view; it does not remove access inherited from a folder or workspace. share page inherit PAGE on or off controls whether a page inherits access from its parent folder or workspace; direct shares remain in place either way. Use --permission private on share page link or share folder link to remove public access. Publicly editable pages or folders can be changed by anyone with the URL. Only the owner can grant Admin access. As with the other CLI commands, pages accept a title or UUID, and folders accept a name or UUID. Workspace sharing is managed through membership rather than page-style permissions: owners add, update, or remove workspace members with the viewer, commenter, editor, or admin role; members can leave a workspace using the owner ID on its Joined workspace line in share workspace show. The output labels your own workspace separately; you cannot leave it. share workspace show also lists your workspace members and pending invitations. With --json, use memberships[].ownerId to select a joined workspace.

Agent Skill

Section titled “Agent Skill”

Install the Metakip skill for tools that support Agent Skills:

Terminal window
metakip skill install

The skill gives supported tools instructions for safe page discovery and exact edits. It does not create a separate copy of your pages.

Keep Tokens Safe

Section titled “Keep Tokens Safe”

Do not paste a token into a chat, commit it to a repository, or put it directly in a command that could be saved in shell history. For non-interactive use, set METAKIP_TOKEN and, for a self-hosted server, METAKIP_URL in the environment.

Section titled “Related Guides”