Type CLI

The Type CLI lets you develop Type Apps, search and read your Type workspace, or manage Type from a terminal and local agent session. Use it to hydrate thread evidence, synchronize documents and skills, and move a local agent conversation into a Type thread.

The executable is type-cli.

If you want to use Type directly from Claude or another supported MCP client without installing a local binary, use Type MCP. Type MCP is also the better fit when an agent runs in a cloud-hosted environment, including Claude Cowork in cloud mode, where the compute cannot access a type-cli binary installed on your machine.

Install the CLI

If you use the Type desktop app, the CLI is bundled with the app:

/Applications/Type.app/Contents/Resources/bin/type-cli install-shell --yes

This installs a type-cli command and configures supported shells so the Type CLI is available on PATH. Restart your shell after installation.

Standalone beta binaries are published from the Type CLI release workflow. To install the latest released CLI with the shell installer:

curl -fsSL https://type.com/install.sh | sh

You can also download a release asset manually, make it executable, then install it into your shell:

chmod +x ./type-cli-linux-x64
./type-cli-linux-x64 install-shell --yes

Check that the CLI is available:

type-cli version

type-cli version shows the installed CLI version and whether it is managed by the Type desktop app, the standalone installer, or a manual/development path.

Both the desktop install path and the standalone shell installer also make a best-effort attempt to install a local Type CLI skill for Claude Code and Codex when those tools are detected on your machine. This lets local agent sessions discover when the Type CLI is useful and how to call it safely.

To repair or re-run only the local agent skill setup:

type-cli install-agent-skills

To target one local agent:

type-cli install-agent-skills --agent claude
type-cli install-agent-skills --agent codex

To skip local agent skill setup during install:

TYPE_CLI_SKIP_AGENT_SKILLS=1 curl -fsSL https://type.com/install.sh | sh

For scripts that only need the version string, use:

type-cli --version

Update the CLI

If you installed the CLI from the Type desktop app, update the Type app to update the bundled CLI.

If you installed the standalone CLI with the shell installer, update it in place:

type-cli update

Updates also refresh existing Type-managed local agent skills so agents see command guidance that matches the current binary. This preserves the local agents you previously installed the skill for; for example, a prior type-cli install-agent-skills --agent claude install is refreshed only for Claude. For desktop-managed installs, type-cli update does not update the app binary, but it still refreshes those existing local skills from the bundled CLI.

Preview the available update without replacing the current binary:

type-cli update --dry-run

Email signup stays in the terminal:

type-cli signup --email you@example.com --name "Acme"

For a local CLI, Google and Slack can go directly to the selected provider and return to a loopback callback on the same machine:

type-cli signup --provider google --email you@example.com --name "Acme"
type-cli signup --provider slack --email you@example.com --name "Acme"

Google signup always shows the account chooser. Type verifies that the authenticated provider email matches --email before provisioning the workspace.

If the CLI runs on a remote host that cannot receive a browser loopback callback, use WorkOS’s device flow instead:

type-cli signup --browser --email you@example.com --name "Acme" --no-open

The device page first asks you to confirm the code printed by the CLI, then lets you authenticate with any method enabled in AuthKit.

type-cli auth login

The CLI opens a browser window and asks you to finish signing in to Type. If you are working in an environment that cannot open a browser, print the login URL instead:

type-cli auth login --no-open

Check your current session:

type-cli auth status

Show the signed-in user and active workspace:

type-cli whoami

Sign out:

type-cli auth logout

Manage CLI analytics

The CLI sends best-effort product analytics for command usage and authenticated CLI outcomes. Analytics failures never change command output or exit codes.

Check the current analytics setting:

type-cli analytics status

Persistently disable or re-enable CLI analytics:

type-cli analytics disable
type-cli analytics enable

Disable analytics for one process without changing the saved preference:

TYPE_CLI_ANALYTICS=0 type-cli skills list --global

Choose a workspace

List the Type workspaces available to your signed-in account:

type-cli orgs list

Set the default workspace:

type-cli orgs use acme

Most commands use your active workspace. If you belong to more than one workspace, pass --org to choose one for a single command:

type-cli skills sync ./skills/pr-review --global --org acme-test

Local agent scripts can use TYPE_ORG instead of repeating --org:

TYPE_ORG=acme-test type-cli skills sync ./skills/pr-review --global

Search the workspace

Search workspace-native messages, threads, Spaces, people, files, docs, and apps with one command:

type-cli search "launch plan"

Search only known target types to reduce work and output:

type-cli search "launch plan" --types threads,docs --limit 5 --json

Accepted --types values are messages, threads, spaces, users, files, docs, and apps. The query must include at least one letter or number. --limit is a per-section cap: it can lower the server default for each requested section but does not raise it.

Search responses include the active organization, current user ID, stable resource IDs, web URLs, match evidence, and per-section pagination metadata. Check hasMore and appliedLimit before concluding that no other matches exist.

Search results are intentionally compact. A thread hit contains a snippet for discovery, not the complete conversation. Hydrate candidate threads before relying on their details:

type-cli threads batch thread_123 thread_456 --per-thread-limit 25 --max-total-chars 24000 --json

Read one thread or continue its pagination cursor:

type-cli threads get thread_123 --limit 50 --max-chars 12000 --json
type-cli threads get thread_123 --cursor '<next-cursor>' --json

List the newest accessible threads across the organization without inventing a search query:

type-cli threads recent --sort created --limit 20 --json

threads recent defaults to creation-time order. Use --sort activity for recently active threads, --space ch_123 to restrict the feed, and --cursor for the next page. This is the direct command for prompts such as “what are the most recently created threads?”

List threads in a Space by recent activity:

type-cli threads list --space ch_123 --status open --limit 20 --json

The Space can be public or a private Space you belong to. Use --from and --to for date filtering and --cursor for the next page. Thread lists are ordered by lastActivityAt; rootCreatedAt is included separately and must not be treated as the list’s sort order.

This search covers content stored in Type. Search Slack, Gmail, Linear, and other external services through their connector or MCP tools.

Develop Type Apps locally

Type App checkouts contain editable frontend and Convex backend source. The frontend can run on your machine while Type hosts the development backend, draft preview, and live release.

Start a new checkout explicitly:

type-cli app create ./inventory-app --space operations --json --no-input
cd ./inventory-app
bun install
type-cli app dev --no-open

Or pull an existing app by its stable ID:

type-cli app pull wart_123 --into ./inventory-app --json --no-input
cd ./inventory-app
bun install
type-cli app dev --no-open

Create and pull responses include a nextActions array for automation. Use --port <port> when the default local frontend port, 5173, is unavailable.

Understand the app states

A local Type App has four distinct states:

Local frontend: Vite serves the current checkout from your machine during app dev.
Shared editable source: Type stores the complete authored tree used by the managed development backend. app dev uploads it at startup and after backend changes.
Hosted draft: For an app that already has a live release, app push creates a preview that teammates can inspect before publishing.
Live release: app publish promotes a hosted draft. For a new app with no release, the first app push prepares and publishes the initial live release.

app dev does not create a hosted draft. Because it updates shared editable source, another development checkout can make your checkout stale even when the Type UI shows no draft.

Push and publish safely

For an app that is already live, create a hosted draft:

type-cli app push --json --no-input

Inspect the returned draft URL. Publishing changes the live app and requires confirmation. In an automated session, ask the user first and then run:

type-cli app publish --yes --json --no-input

The first push for a new app publishes the initial live release. It stops instead of publishing when a non-interactive caller omits --yes. After the user explicitly approves the live release, run:

type-cli app push --yes --json --no-input

If the app requests connections, publication may require approval for an exact set of capabilities. Review those capabilities before supplying --yes.

Synchronize without Git

Git is optional. Type records a local whole-tree base in .type/checkout.json and compares it with local authored source and current shared editable source.

If only the remote source changed, pull safely fast-forwards the checkout.
If only local source changed, pull preserves it.
If both changed, pull reports reason: "diverged" and changes no files.
Dev and push use a source generation check so a stale checkout cannot overwrite newer shared source.

For scripts and agents, inspect error.details.reason, filesModified, sourceUploaded, and safeCommands. Treat filesModified and sourceUploaded independently. If sourceUploaded is true, shared source already advanced; do not blindly retry.

On divergence, use the recommended side-by-side command:

type-cli app pull --app-id wart_123 --into ../inventory-app-latest --json --no-input

Compare the directories with Git or ordinary filesystem tools. Run a command marked requiresExplicitUserApproval only after the user approves it. A forced pull backs up the previous tree under .type/backups/; recovery files are in <backupDirectory>/files/, while manifest.json contains metadata. Keep the fresh checkout’s .type/* and managed AGENTS.md when reapplying authored files.

Inspect and change access

Reading access is non-mutating:

type-cli app access --json

Scope changes require confirmation or --yes. app share makes an app public; it is not a read-only URL command. Ask the user before either operation:

type-cli app access --workspace --yes --json --no-input
type-cli app share --yes --json --no-input

Use type-cli app open --no-open --json when you only need the app URL and must not launch a browser.

Work with Type documents

Use type-cli documents when you want Markdown files on your machine to become editable Type documents, or when you want to bring an existing Type document down for local editing.

List recent documents you can access:

type-cli documents list

Search by title or Markdown content:

type-cli documents list "launch plan"

Create a document from a local Markdown file:

type-cli documents push --file ./docs/launch-plan.md --title "Launch Plan" --agent @engineering

push is best for one-off uploads, stdin, or scripts that already know the document ID. By default, new documents are channel-scoped. Add --public only when the document should be accessible to anyone with the link:

type-cli documents push --file ./docs/status.md --title "Weekly Status" --agent @engineering --public

Update an existing document by ID:

type-cli documents push wart_123 --file ./docs/launch-plan.md

Use sync for local files you expect to maintain over time. The first sync creates the document and records a local mapping in ~/.type; later syncs update the same Type document:

type-cli documents sync --file ./docs/launch-plan.md --title "Launch Plan" --agent @engineering

After the first sync, you can run:

type-cli documents sync --file ./docs/launch-plan.md

Link an existing Type document to a local file before syncing it:

type-cli documents sync --file ./docs/launch-plan.md --link wart_123

Pull an existing Type document into a local Markdown file:

type-cli documents pull wart_123 --file ./docs/launch-plan.md

Write a pulled document to stdout instead:

type-cli documents pull wart_123 --file -

Preview create, update, or sync work before writing:

type-cli documents sync --file ./docs/launch-plan.md --title "Launch Plan" --agent @engineering --dry-run

Document commands return share links. In agent workflows, pass --json --no-input so the agent can parse document IDs and URLs without prompts.

Sync skills to an agent

Use type-cli skills sync to create or update a Type skill from a local skill folder.

type-cli skills sync ./skills/pr-review --agent @engineering

The skill folder should include a SKILL.md file. Optional scripts, references, and assets folders are uploaded with the skill.

On the first sync, Type creates the skill and attaches it to the agent. On later syncs, Type updates the existing skill.

Preview the change without uploading:

type-cli skills sync ./skills/pr-review --agent @engineering --dry-run

Create a new skill every time instead of updating a linked skill:

type-cli skills push ./skills/pr-review --agent @engineering

If a skill with the same name already exists for the target, push fails by default. Use --force to update the existing same-name skill when the CLI can resolve it unambiguously:

type-cli skills push ./skills/pr-review --agent @engineering --force

List skills attached to an agent:

type-cli skills list --agent @engineering

Inspect a skill and its packaged files:

type-cli skills inspect skill_123

Sync skills to the workspace library

Use --global to create or update workspace-level skills instead of attaching the skill to one agent.

type-cli skills sync ./skills/pr-review --global

List workspace-level skills:

type-cli skills list --global

Use --link when one local skill directory should sync to an existing Type skill:

type-cli skills sync ./skills/pr-review --global --link skill_123

Skill packages currently support UTF-8 text files. Binary skill assets are not supported yet.

Push a local agent session

Use type-cli sessions push to move a local Claude or Codex session, or an exported agent transcript, into Type.

Choose exactly one push source: use --current to discover the active provider session, or use --file <path> to push a specific transcript file. The CLI rejects commands that pass both.

type-cli sessions push --from claude --current --agent @engineering

type-cli sessions push --from codex --current --agent @engineering

You can also push a specific transcript file:

type-cli sessions push --file ./handoff/session.jsonl --agent @engineering

Type creates a new thread and returns the thread URL. The pushed thread includes the transcript and provider metadata so you can continue the work on type.com.

Add a title:

type-cli sessions push --file ./handoff/session.jsonl --agent @engineering --title "Checkout bug investigation"

File attachments and redaction are not supported yet. If you pass --include-files or --redact, the CLI returns an unsupported error instead of silently ignoring it.

type-cli sessions push --file ./handoff/session.jsonl --agent @engineering --include-files "notes/*.md"

Preview what will be uploaded:

type-cli sessions push --file ./handoff/session.jsonl --agent @engineering --dry-run

If the current Claude or Codex session is too large for the inline push limit, push the newest complete records that fit:

type-cli sessions push --from codex --current --agent @engineering --tail

Use the CLI from local agents

Local agents can call the same commands people use. For reliable agent workflows, use --json and --no-input:

type-cli skills sync ./skills/pr-review --agent @engineering --json --no-input

For retrieval tasks, use a discovery-then-hydration sequence:

type-cli search "checkout regression" --types threads,messages,docs --json --no-input
type-cli threads batch thread_123 thread_456 --json --no-input

Do not answer from a search snippet when the thread body is material to the answer. Use threads batch for several candidates, threads get for one candidate, and follow nextCursor when the response is truncated.

In JSON mode, stdout contains one JSON object. Progress and warnings are written to stderr so the response stays parseable.

Successful responses include IDs and URLs:

{
  "ok": true,
  "operation": "skill.sync",
  "skill": {
    "id": "skill_123",
    "handle": "pr-review",
    "url": "https://type.com/acme/skills/skill_123"
  },
  "agent": {
    "id": "agent_456",
    "handle": "engineering"
  }
}

If the CLI needs a decision and --no-input is set, it fails with a structured error instead of prompting.

Resource references

Commands accept stable IDs and handles.

Resource	Accepted references
Agent	`@handle`, `agent_...`
Skill	`skill_...`, skill handle
Workspace	workspace slug, organization ID

Use IDs in scripts and agent workflows. Handles are easier for humans but can become ambiguous.

Files and secrets

The CLI never uploads known secret files by default. It excludes files such as .env, private keys, local credential stores, node_modules, and .git.

Use --dry-run before large session pushes to review what will be sent to Type.

Common commands

Task	Command
Sign in	`type-cli auth login`
Check session	`type-cli auth status`
List workspaces	`type-cli orgs list`
Set active workspace	`type-cli orgs use acme`
List agents	`type-cli agents list`
Search workspace content	`type-cli search "launch plan" --json`
List newest workspace threads	`type-cli threads recent --sort created --json`
List threads in a Space	`type-cli threads list --space ch_123 --json`
Read one thread	`type-cli threads get thread_123 --json`
Read candidate threads	`type-cli threads batch thread_123 thread_456 --json`
List Type Apps	`type-cli app ls`
Create a Type App checkout	`type-cli app create ./my-app --space operations`
Pull a Type App checkout	`type-cli app pull wart_123 --into ./my-app`
Run a Type App locally	`type-cli app dev --no-open`
Create an update draft	`type-cli app push`
Publish an approved update	`type-cli app publish --yes`
Inspect app access	`type-cli app access`
List documents	`type-cli documents list`
Create a document	`type-cli documents push --file ./doc.md --title "Title" --agent @engineering`
Sync a maintained document	`type-cli documents sync --file ./doc.md --title "Title" --agent @engineering`
Pull a document	`type-cli documents pull wart_123 --file ./doc.md`
Sync a skill	`type-cli skills sync ./skill --agent @engineering`
Preview skill sync	`type-cli skills sync ./skill --agent @engineering --dry-run`
Push a transcript	`type-cli sessions push --file ./session.jsonl --agent @engineering`
Push current Claude session	`type-cli sessions push --from claude --current --agent @engineering`
Push current Codex session	`type-cli sessions push --from codex --current --agent @engineering`
Install shell command	`type-cli install-shell --yes`
Show CLI version	`type-cli version`
Update standalone CLI	`type-cli update`

Troubleshooting

If type-cli is not available in your shell, rerun type-cli install-shell --yes, then restart your shell. You can always invoke the bundled desktop binary directly:

/Applications/Type.app/Contents/Resources/bin/type-cli auth status

If type-cli is not found, reinstall the CLI from the Type desktop app or add the standalone binary to your shell path.

If a command says you are not signed in, run:

type-cli auth login

If a command cannot find an agent, use its agent ID or exact handle:

type-cli skills sync ./skill --agent agent_123

For documents, use the document ID from type-cli documents list. Document IDs usually start with wart_.

If install-shell needs to write somewhere other than /usr/local/bin or ~/.local/bin, pass an explicit install directory:

type-cli install-shell --install-dir "$HOME/bin" --yes

If the install target already exists and is not the current Type CLI symlink, replace it explicitly:

type-cli install-shell --force --yes

If a local agent cannot answer an interactive prompt, rerun the command with --json --no-input and use the structured error to decide the next step.

Report a bug

Report a bug

Type CLI

Install the CLI

Update the CLI

Manage CLI analytics

Choose a workspace

Search the workspace

Develop Type Apps locally

Understand the app states

Push and publish safely

Synchronize without Git

Inspect and change access

Work with Type documents

Sync skills to an agent

Sync skills to the workspace library

Push a local agent session

Use the CLI from local agents

Resource references

Files and secrets

Common commands

Troubleshooting

Type CLI

Install the CLI

Update the CLI

Sign up

Sign in

Manage CLI analytics

Choose a workspace

Search the workspace

Develop Type Apps locally

Understand the app states

Push and publish safely

Synchronize without Git

Inspect and change access

Work with Type documents

Sync skills to an agent

Sync skills to the workspace library

Push a local agent session

Use the CLI from local agents

Resource references

Files and secrets

Common commands

Troubleshooting