# Type CLI

> Develop Type Apps locally, search and read a Type workspace, use integrations, synchronize content, and hand local agent work to Type.

Canonical page: https://docs.type.com/reference/type-cli/

The Type CLI lets you develop Type Apps, search and read your Type workspace, use your Type integrations, or manage Type from a terminal and local agent session. Use it to hydrate thread evidence, work with connected services, 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](https://docs.type.com/reference/type-mcp/index.md). 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:

```sh
/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:

```sh
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:

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

Check that the CLI is available:

```sh
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:

```sh
type-cli install-agent-skills
```

To target one local agent:

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

To skip local agent skill setup during install:

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

For scripts that only need the version string, use:

```sh
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:

```sh
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:

```sh
type-cli update --dry-run
```

## Sign up

Email signup stays in the terminal:

```sh
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:

```sh
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:

```sh
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.

## Sign in

Sign in before running workspace commands:

```sh
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:

```sh
type-cli auth login --no-open
```

Check your current session:

```sh
type-cli auth status
```

Show the signed-in user and active workspace:

```sh
type-cli whoami
```

Sign out:

```sh
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:

```sh
type-cli analytics status
```

Persistently disable or re-enable CLI analytics:

```sh
type-cli analytics disable
type-cli analytics enable
```

Disable analytics for one process without changing the saved preference:

```sh
TYPE_CLI_ANALYTICS=0 type-cli skills list --global
```

## Choose a workspace

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

```sh
type-cli orgs list
```

Set the default workspace:

```sh
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:

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

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

```sh
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:

```sh
type-cli search "launch plan"
```

Search only known target types to reduce work and output:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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. Use the integration commands below for Slack, Gmail, Linear, and other connected services.

## Manage Spaces and channels

Spaces bring people and Type together. Each Space has its own agent; channels organize conversations within it. Space and channel references accept an ID, slug, or exact name.

```sh
type-cli spaces list
type-cli spaces get operations
type-cli spaces create "Daily brief" --description "Morning summaries" --private
type-cli spaces update daily-brief --name "Team brief"
type-cli channels list --space daily-brief
type-cli channels create Alerts --space daily-brief
type-cli channels rename Alerts "Ops alerts" --space daily-brief
```

Use `spaces members`, `add-member`, `remove-member`, `join`, and `leave` to manage membership:

```sh
type-cli spaces members daily-brief
type-cli spaces add-member daily-brief someone@example.com
type-cli spaces join operations
```

Space autoreply controls webhook replies and the default behavior for new threads. Channel autoreply controls replies to new threads in that channel:

```sh
type-cli spaces autoreply daily-brief on
type-cli channels autoreply General on --space daily-brief
```

Archiving hides a Space or channel. Merging moves content into a target and archives the source. Space merges require an organization admin. These operations, removing members, leaving a Space, and deleting automations ask for confirmation; non-interactive callers must supply `--yes` after approval.

```sh
type-cli spaces archive old-space --yes
type-cli spaces merge old-space --into operations --yes
type-cli channels merge Alerts --into General --space operations --yes
```

## Run scheduled actions

Scheduled actions run the Space's agent on a timetable. Create one with instructions and a schedule:

```sh
type-cli scheduled-actions create --space daily-brief --name "Morning brief" \
  --every weekdays --at 09:00 --timezone America/Los_Angeles \
  --instructions-file ./brief.md
```

`--every` accepts `day`, `weekdays`, `weekends`, comma-separated weekdays such as `mon,wed,fri`, intervals `15m`, `30m`, `1h`, `2h`, or `4h`, and `month`. Monthly schedules use `--day-of-month 15` or a pattern such as `--monthly first-mon` or `--monthly last-fri`.

`--timezone` accepts an IANA timezone such as `America/Los_Angeles`, `Europe/London`, or `UTC`. Invalid zones are rejected. New schedules default to the machine's local timezone and `09:00`. Updates preserve omitted fields, so changing only `--at` keeps the existing weekdays and timezone:

```sh
type-cli scheduled-actions update atask_123 --space daily-brief --at 10:00
type-cli scheduled-actions update atask_123 --space daily-brief --timezone Europe/London
```

New actions start disabled. Test before enabling:

```sh
type-cli scheduled-actions test atask_123 --space daily-brief --follow
type-cli scheduled-actions enable atask_123 --space daily-brief
type-cli scheduled-actions history --space daily-brief
```

Tests run in a private thread and print its URL. `--follow` streams available text and checks the saved run status if streaming is unavailable. It exits non-zero on failure, cancellation, or timeout. The default timeout is 300 seconds; use `--timeout <seconds>` to change it. A timeout stops waiting without cancelling the server run.

Use `--channel <channel>` to select a destination. `--slack-channel <#name|id>` also posts to a Slack channel already linked to the Space. `--model <id> --effort <level> [--fast]` configures the run; `--default-model` clears overrides on update. Run `type-cli scheduled-actions --help` for supported models and flags. Instructions can reference workspace skills as `/skill-handle`; find handles with `type-cli skills list --global`.

## Configure synced events

Synced events bring activity from Slack, GitHub, Linear, webhooks, RSS, email, or new threads into a Space. List existing sources or create one:

```sh
type-cli synced-events list --space daily-brief
type-cli slack channels
type-cli synced-events create --space daily-brief --source slack --slack-channel "#sales-updates"
type-cli synced-events create --space daily-brief --source rss --url https://example.com/feed.xml --poll-minutes 30
type-cli synced-events create --space daily-brief --source webhook --service Stripe --instructions "Summarize payments"
```

Slack, GitHub, and Linear require a connected integration. Use `type-cli integrations connect <provider>` first, and pass `--integration <id>` when needed. Slack supports `--trigger mentions|posts|all`. Email sources use `--username <local-part>`; their output includes the receiving address. New-thread sources start disabled and can be tested, then enabled.

```sh
type-cli synced-events test whsrc_123 --space daily-brief --follow
type-cli synced-events send whsrc_123 --space daily-brief --payload ./sample.json
type-cli synced-events poll rsssrc_123 --space daily-brief
type-cli synced-events history --space daily-brief
```

`send` delivers a real webhook event; `poll` checks an RSS feed. Webhook sources created with `--secret` verify signatures, so pass the same secret to `send`. Webhook replies follow the Space autoreply setting. Slack, GitHub, Linear, and email sources cannot be paused; delete them to stop incoming events. Use `type-cli synced-events --help` for source-specific flags.

## Use integrations

List the integration instances available to you in the active organization:

```sh
type-cli integrations list --json
```

Each entry includes its stable `organizationIntegrationId`, service name, availability, and effective `accessMode`. Type evaluates it for the signed-in CLI user in sidekick context, using the same personal-or-organization credential selection and granular permission policy as Type. Space-level grants do not affect CLI access.

Inspect the permitted tools and their exact argument schemas before calling one:

```sh
type-cli integrations tools google-email-calendar \
  --integration orgint_123 \
  --json
```

Then call a returned tool. For example, a request for recent email can use the user's personal Gmail account selected by Type:

```sh
type-cli integrations call google-email-calendar gmail_search_emails \
  --integration orgint_123 \
  --args '{"query":"newer_than:7d","maxResults":10}' \
  --json --no-input
```

Type keeps OAuth tokens and other credentials on the server; the CLI receives only tool metadata and results. If an integration supports personal accounts, Type applies its normal personal-versus-workspace credential selection for the signed-in user. Pass `--integration` whenever more than one installed instance provides the same service.

Read-only access is checked on both discovery and execution: CLI tool listings omit write tools, and a direct attempt to call one is rejected. The provider credential itself is not re-scoped, so calls that send, post, edit, delete, or otherwise change external data still require full access and should be treated as consequential operations.

### Add and remove integrations

List native integrations and Custom API setup capabilities, then inspect installed personal and organization connections:

```sh
type-cli integrations available --json
type-cli integrations connections --json
```

These commands include Custom API connections. Provider-catalog setup is not supported by the CLI.

Start a personal Gmail connection:

```sh
type-cli integrations connect google-email-calendar \
  --scope personal \
  --no-open --json
```

For OAuth connectors, the returned `authUrl` goes directly to the provider. Open it to authorize the connection. The callback returns to Type so it can finish setup. Jira and connectors that need API keys, service-account credentials, or other browser-bound configuration instead return the exact Type setup URL. The CLI does not collect provider secrets.

When a connector supports both scopes, such as Linear, choose one explicitly:

```sh
type-cli integrations connect linear --scope personal --no-open --json
type-cli integrations connect linear --scope organization --no-open --json
```

Use `--integration <id>` to reconnect an exact instance. GitHub personal setup requires an exact instance. Use `--new` only for a native connector that supports another organization instance, such as GitHub. Native Google OAuth accepts a string-valued config object when needed:

```sh
type-cli integrations connect google_analytics \
  --config '{"ga4PropertyId":"properties/123"}' \
  --no-open --json
```

Disconnecting changes stored connection state and asks for confirmation. For non-interactive use, get approval first and pass `--yes`:

```sh
type-cli integrations disconnect \
  --integration orgint_123 \
  --scope personal \
  --yes --json --no-input
```

If an instance has both personal and organization credentials, `--scope` is required. Disconnecting a personal account always targets the signed-in user's credential. Disconnecting an organization connection uses the same workspace-admin or integration-manager authorization as Type's web UI.

### Connect and use a Custom API

Prepare the nonsecret configuration in your terminal or local agent session. Type opens a form where you enter the credential:

```sh
type-cli integrations connect custom \
  --scope personal \
  --config '{"name":"Warehouse API","baseUrl":"https://api.example.com","authScheme":"bearer","validationRequest":{"path":"/v1/me"}}' \
  --json --no-input
```

Use `--scope organization` for a shared credential. The draft requires a name and HTTPS base URL. It can include documentation, connection settings, and a read-only validation request. Supported authentication schemes are `bearer`, `x_api_key`, `custom_header`, `oauth2_client_credentials`, and `none`. Custom headers require `authHeaderName`; OAuth client credentials require `oauthClientId` and `oauthTokenUrl`.

Never put a credential in `--config`, command arguments, or agent messages. Enter it only in Type and press **Save**. Use `--no-open` to receive the setup URL without opening a browser.

The connect result provides an attempt ID and a `waitCommand`. Run that command to monitor the exact setup, then run the returned `verifyCommand`:

```sh
type-cli integrations wait <attempt-id> --json --no-input
type-cli integrations verify <attempt-id> --json --no-input
```

`wait` confirms that the credential was saved. `verify` makes the draft's GET request and marks setup ready after a successful response. If the draft omitted a validation request, supply `--args '{"path":"/v1/me"}'` to `verify`. If verification fails because the test request needs correction, retry the same attempt with a safe GET request in `--args`. If the credential or connection configuration needs replacement, use the returned `retryIntegrationId` and preserve the original connection scope: `type-cli integrations connect custom --integration <retryIntegrationId> --scope <original-scope> --config '<nonsecret-draft>' --json --no-input`. Supply the original or corrected nonsecret draft, then wait and verify the new attempt.

Call a ready Custom API by its exact integration ID:

```sh
type-cli integrations request --integration orgint_123 \
  --args '{"path":"/v1/items","query":{"limit":3}}' --json --no-input
```

Requests default to GET. POST, PUT, PATCH, and DELETE require approval; after approval, pass `--yes`. Request arguments support `path`, `query`, `headers`, and an optional `body` with `bodyEncoding` set to `json` or `form`. Type injects the stored credential, bounds and redacts responses, and does not follow redirects. If a write fails after it may have reached the provider, inspect provider state before retrying.

Custom API connections use the same disconnect and permission commands as native integrations. See [Connect a Custom API](https://docs.type.com/connectors-and-skills/custom-apis/index.md) for the setup flow in Type.

### Manage CLI integration permissions

Permission management is available when the `integrations-granular-permissions` feature switch is enabled for the organization. Inspect one or all native and Custom API integration policies:

```sh
type-cli integrations permissions list --json
type-cli integrations permissions list --integration orgint_123 --json
```

The output removes Space grants and reports the signed-in user's CLI-effective mode. For a shared organization connection, workspace and explicit user grants are additive: the highest applicable mode wins. A user-level `read_only` grant does not reduce a workspace-level `full` grant.

For example, make a connection read-only by default while allowing two people to write:

```sh
type-cli integrations permissions set \
  --integration orgint_123 --workspace --mode read_only --yes
type-cli integrations permissions set \
  --integration orgint_123 --user alex@example.com --mode full --yes
type-cli integrations permissions set \
  --integration orgint_123 --user pat@example.com --mode full --yes
```

The actor changing a shared connection's grants must be a workspace owner/admin or a manager of that integration. A grant recipient does not need to be an integration manager.

A user can cap their own personal credential without being an integration manager:

```sh
type-cli integrations permissions set \
  --integration orgint_123 --personal --mode read_only --yes
```

`--personal` always means the signed-in user's own personal credential. `--user <member>` means an explicit grant on a shared organization connection; the member can be `me`, an exact organization-user or user ID, an email address, or an exact display name.

Remove an explicit shared grant with `clear`:

```sh
type-cli integrations permissions clear \
  --integration orgint_123 --user pat@example.com --yes
```

Personal modes cannot be cleared independently. Set the mode to `read_only` or `full`, or disconnect the personal account. All permission mutations prompt by default; automated callers should use `--no-input` and add `--yes` only after the user approves the exact change.

## 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:

```sh
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:

```sh
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:

1. **Local frontend:** Vite serves the current checkout from your machine during `app dev`.
2. **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.
3. **Hosted draft:** For an app that already has a live release, `app push` creates a preview that teammates can inspect before publishing.
4. **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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
type-cli documents list
```

Search by title or Markdown content:

```sh
type-cli documents list "launch plan"
```

Create a document from a local Markdown file:

```sh
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:

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

Update an existing document by ID:

```sh
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:

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

After the first sync, you can run:

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

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

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

Pull an existing Type document into a local Markdown file:

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

Write a pulled document to stdout instead:

```sh
type-cli documents pull wart_123 --file -
```

Preview create, update, or sync work before writing:

```sh
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.

```sh
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:

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

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

```sh
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:

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

List skills attached to an agent:

```sh
type-cli skills list --agent @engineering
```

Inspect a skill and its packaged files:

```sh
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.

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

List workspace-level skills:

```sh
type-cli skills list --global
```

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

```sh
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.

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

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

You can also push a specific transcript file:

```sh
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:

```sh
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.

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

Preview what will be uploaded:

```sh
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:

```sh
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`:

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

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

```sh
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:

```json
{
  "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 |
| Space | `ch_...`, Space slug, exact name |
| Channel | channel ID, channel slug, exact name within the Space |

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 Spaces | `type-cli spaces list` |
| List channels | `type-cli channels list --space operations` |
| List scheduled actions | `type-cli scheduled-actions list --space operations` |
| Test an automation | `type-cli scheduled-actions test atask_123 --space operations --follow` |
| List synced events | `type-cli synced-events list --space operations` |
| Discover Slack channels | `type-cli slack channels` |
| 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:

```sh
/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:

```sh
type-cli auth login
```

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

```sh
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:

```sh
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:

```sh
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.