Type CLI

The Type CLI lets you discover public library skills, develop Type Apps, search and read your Type workspace, use integrations, and run agent tasks from a terminal or local agent session. Use it to hydrate thread evidence, work with connected services, synchronize documents and skills, start new threads, push local agent sessions into Type, and reply to existing threads.

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.

Start a task, push a session, or reply in a thread

Choose the CLI command that matches the work:

Goal	Command	Result
A new task for a Space agent	`type-cli threads create`	Creates a new thread and starts the agent
A local Claude or Codex session, or an exported transcript	`type-cli sessions push`	Creates a new thread with the transcript
A message or update in a thread that already exists	`type-cli threads reply`	Adds a reply to that thread as the signed-in user

# Push the current session into a new thread (use claude or codex).
type-cli sessions push --from codex --current --space engineering --json

# Post an update using the thread.id returned by the push.
type-cli threads reply thread_123 --message "@Jane Doe ready for review" --json

# Or read the reply text from a file.
type-cli threads reply thread_123 --file ./update.md --reply-mode chat --json

You can reply to any accessible, open Space thread; it does not need to come from a session push. Find its ID with threads recent, threads list, or search. Each sessions push creates another new thread, so use threads reply for follow-up updates. Replies with a resolved user mention default to a Team message; other replies default to an AI prompt. Use --reply-mode chat to post an update without triggering the agent, or --reply-mode prompt to ask the agent to respond.

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 binaries are published for macOS, Linux, and Windows x64. On macOS or Linux, install the latest released CLI with the shell installer:

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

On Windows x64, run this in PowerShell:

irm https://type.com/install.ps1 | iex

The Windows installer verifies the download checksum, installs type-cli.exe in %USERPROFILE%\.type\bin, and adds that directory to your user PATH. It does not require administrator access. Restart your terminal and Claude Code after installing, then run type-cli --version.

If the version still looks old, run Get-Command type-cli -All in PowerShell to find earlier installations on PATH. You can run the new installation explicitly with & "$env:USERPROFILE\.type\bin\type-cli.exe" --version.

Use type-cli update for subsequent standalone updates. If an older Windows CLI says updates are only supported on macOS and Linux, rerun the PowerShell installer to replace it. For a manual download, use the Windows x64 executable; downloaded binaries can be run directly without install-shell.

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 set up Claude Code and Codex when those tools are detected on your machine, so local agent sessions prefer Type for automations, apps, integrations, and skills:

A type-cli skill is installed under ~/.claude/skills/type-cli/ (Claude Code) and ~/.agents/skills/type-cli/ (Codex) with workflow guidance for Type MCP and the CLI.
A Type-managed block is added to the agent’s global instruction file: ~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex. The block is delimited by  and  markers; everything outside the markers is left untouched, and only the block is refreshed on later installs and updates. Remove the block to opt out.

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 macOS/Linux shell installer or Windows PowerShell 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

type-cli update supports macOS, Linux, and Windows x64. It does not replace a manually installed binary; download a new release asset instead.

Start signup from the terminal and authenticate in your browser:

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 checks signup eligibility after browser authentication and before registering the CLI’s agent identity.

New workspaces require either a card or a connected Claude or Codex subscription. Choose a subscription during signup:

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

After Type authentication, the CLI prints a browser link to connect the selected subscription. The subscription powers agent turns immediately, and the workspace keeps its $10 in Type credits as fallback when the subscription reaches its usage limit. Explicit model choices are preserved. Without --subscription, the browser offers both subscriptions and card checkout. Card checkout starts a free trial with nothing due today and an automatically renewing plan afterward; an owner or admin must complete checkout. Review the price and trial duration in checkout.

JSON output includes billingRequired and billingUrl (null when signup requirements are satisfied). ok: true means signup credentials were saved, not that billing is complete. The CLI never asks for card details. Open billingUrl in your browser and connect the subscription or add a card, then run type-cli signup complete --json --no-input to check again. Use signup complete --subscription claude or signup complete --subscription codex to select a connection when resuming. This also works after auth login for the selected workspace. If billing verification temporarily fails, signup preserves its checkpoint and instructs you to retry signup complete. Authentication failures retain their original sign-in guidance.

The credential created by signup is bound to the new workspace and is read-only: it supports whoami, search, and threads reads. Run type-cli auth login before using integrations, documents, workspace skills, sessions, or other write commands.

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

The CLI stores its session in your operating system keychain. If Linux’s libsecret, Secret Service, or session bus is unavailable, it falls back to a plaintext file under ~/.type/credentials/ (TYPE_CONFIG_DIR/credentials/ when configured), with 0600 file permissions and 0700 permissions on newly created credential directories. The CLI prints the file location to stderr when saving there. Permission denials, locked keyrings, and unexpected keychain errors still fail the command.

Once a profile uses file storage, it continues reading and updating that file even if the keychain becomes available later. Signing out deletes the file, attempts to remove the keychain entry, and removes the profile’s saved settings; unavailable keychain entries cannot be removed until the service is available.

Configuration and environment

CLI settings live in ~/.type (config.json, plus the document and skill mapping files). Set TYPE_CONFIG_DIR to use a different directory.

Every command accepts these global options:

Option	Environment variable	Purpose
`--json`	`TYPE_JSON=1`	Print one JSON object to stdout; progress goes to stderr.
`--no-input`	`TYPE_NO_INPUT=1`	Fail with a structured error instead of prompting.
`--org <org>`	`TYPE_ORG` or `TYPE_ORG_ID`	Choose the workspace for one command.
`--profile <name>`	`TYPE_PROFILE`	Keep separate sessions, for example for two Type accounts.
`--server <url>`	`TYPE_SERVER_URL`	Type API base URL; defaults to `https://api.type.com`.
`--app <url>`	`TYPE_APP_URL`	Type web app base URL; defaults to `https://type.com`.

Unknown options are rejected, so check type-cli <command> --help for the exact flags a command accepts.

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

Query workspace analytics

workspace-analytics provides the same health, usage, and cost queries as Type’s built-in organization analytics tools. These are authenticated, read-only workspace queries. Access is enforced by the server and generally requires an administrator or owner. Use --org <org> to select a workspace; permission errors exit with code 4.

This command group is independent of analytics status|enable|disable, which only manages CLI telemetry preferences. Disabling CLI telemetry does not disable workspace analytics queries.

type-cli workspace-analytics health --period last_7_days --json
type-cli workspace-analytics health --space ch_123 --json
type-cli workspace-analytics catalog --json
type-cli workspace-analytics usage summary --json
type-cli workspace-analytics usage adoption --period last_30_days --json
type-cli workspace-analytics usage trend --metric active_members --grain week --json
type-cli workspace-analytics usage series --metric ai_teammate_invocations --grain day --dimension source --limit 8 --json
type-cli workspace-analytics usage breakdown --metric failed_invocations --dimension space --limit 25 --json
type-cli workspace-analytics costs billing-period --json
type-cli workspace-analytics costs summary --json
type-cli workspace-analytics costs trend --grain day --scope space --scope-id ch_123 --json
type-cli workspace-analytics costs series --grain day --dimension model --measure input_tokens --json
type-cli workspace-analytics costs breakdown --dimension member --json
type-cli workspace-analytics costs space-detail --space ch_123 --json

Command	Data
`health`	Organization overview, findings, execution outcomes, running work, blockers, automation failures, and connection health. Add `--space <space-id>` for the Space detail view.
`catalog`	Usage metrics, compatible dimensions, grains, range limits, privacy rules, and limitations.
`usage summary`	Workspace activity totals and prior-period comparisons.
`usage adoption`	Member activity and adoption.
`usage trend`	One `--metric` over time, with required `—grain day
`usage series`	A `--metric` grouped over time, with required `--grain` and `--dimension`.
`usage breakdown`	A ranked `--metric` by required `--dimension`.
`costs billing-period`	Current billing dates, allowance, credits, token usage, and a reusable analytics date range.
`costs summary`	Cost and token totals with prior-period comparisons.
`costs trend`	Cost over time, with required `--grain`.
`costs series`	Grouped cost, input tokens, output tokens, or model calls, with required `--grain` and `--dimension`. Each bucket retains aligned cost and token totals.
`costs breakdown`	Ranked costs by required `—dimension member
`costs space-detail`	Detailed cost makeup for required `--space <space-id>`.

Range options apply to health and all usage/cost views except catalog and costs billing-period:

--period last_7_days|last_30_days|last_90_days selects a trailing period. Omitting range options uses the server default, currently the last 30 days.
--since <date|timestamp> selects a live range ending at request time. Add --until <date|timestamp> for a fixed range. Do not combine these with --period.
The start is inclusive and the end is exclusive. Date-only inputs mean midnight UTC; timestamps must include a timezone. For all of September, use --since 2026-09-01 --until 2026-10-01. Future or reversed ranges are rejected; the server enforces the catalog’s maximum range length.

Trend and series views accept --scope organization|space|channel|member, defaulting to organization. Non-organization scopes require --scope-id <stable-id>. --space is only for health and costs space-detail; use a stable Space ID from the health overview or spaces list, not a name or slug.

Usage dimensions come from catalog; cost dimensions are member, space, channel, and model. costs series --measure accepts cost (default), input_tokens, output_tokens, or model_calls. Breakdown limits are 5–100 (default 25); series limits are 3–20 (default 8), with remaining values grouped into Other. Unsupported options for a selected view fail with exit code 2 instead of being ignored. For Space cost detail, choose a known Space from costs breakdown --dimension space and use the same date range. A Space with no recorded costs in the range returns not_found (exit code 8); widen the range or select a Space with cost records.

--json returns { "ok": true, "operation": "workspace-analytics.<view>", "data": ... }. data preserves the full server response, including schema version, comparisons, cost basis, privacy metadata, and limitations where present. Without --json, the command prints the same data as formatted JSON. Cost amounts are USD micros before allowances and credits; input tokens include cached input. Health does not measure uptime, missed schedules, queue delay, or integration sync freshness. Personal Sidekick details remain subject to the same server privacy rules as Type’s tools.

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

Thread reads (threads get and threads batch) include attachments in each message’s files and images arrays. Uploaded attachments include fileId, filename, mimeType, sizeBytes, and download: { status: "available", url, expiresAt }. URLs expire after one hour; read the thread again to refresh them. The same image can appear in both arrays; deduplicate by fileId only when it is present, and preserve images without a fileId.

To save original file bytes locally using a fresh URL:

type-cli files download file_123 --output ./report.pdf --json

The result includes fileId, an absolute path, filename, mimeType, and bytesWritten. The parent directory must exist. Existing files are never overwritten, and failed or incomplete downloads are not published to the output path. The command uses the signed-in user’s attachment permissions.

Unavailable attachments retain their metadata and return download: { status: "unavailable", reason, retryable }; other attachments and the thread remain readable. Reasons include not_found_or_inaccessible, upload_pending, upload_failed, not_downloadable, and temporarily_unavailable. External images without a Type file ID retain their original url and report external_url; Type does not sign or proxy these URLs. For expired download links, use files download with the stable file ID or fetch the thread again.

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?” Add --waiting-on-input to return only threads where AI is currently waiting for a person’s answer.

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. Add --waiting-on-input to find threads where AI is waiting for a person’s answer. Answered questions do not match; the filter is applied before pagination.

This search covers content stored in Type. Use the integration commands below for Slack, Gmail, Linear, and other connected services.

Start and complete an agent task

Use threads create to start work in a Space. It creates a new thread in the Space’s default channel and returns its ID and URL before the agent finishes. A normal auth login session is required; a signup-issued read-only credential cannot start a task.

type-cli threads create --space engineering --message "Summarize the latest release" --json
type-cli threads create --space engineering --file ./task.md --json

Optional --harness claude|codex, --model <model>, and --effort <effort> pin the run settings. A model implies its compatible harness; unsupported combinations fail. For coding work, --ref <full-40-character-commit-sha> starts from a commit already pushed to the Space’s attached GitHub repository. The CLI does not commit or push local files. Without --ref, the Space does not need a repository.

To attach a local file, upload it into the target Space and pass the returned fileId to threads create or threads reply. --file reads prompt text; --file-id attaches bytes. Repeat --file-id for up to 20 attachments.

type-cli files upload ./input.csv --space engineering --json
type-cli threads create --space engineering --file ./task.md --file-id file_123 --json

Use threads status for one snapshot or threads watch to observe execution until completion, failure, cancellation, required input, or the observation deadline. The default deadline is 300 seconds; --timeout accepts 1–3600 seconds. In JSON mode, watch returns a compact selected-run result with status, terminal, stopReason, output text and file IDs, pending approvals, history, and nextActions. Add --include-messages for a bounded message page or --max-chars to change the default 8,000-character text budget.

type-cli threads status thread_123 --json
type-cli threads watch thread_123 --timeout 300 --json

A watch timeout returns ok: true with stopReason: "timeout" and a resume action; it does not stop the remote task. Closing the terminal or pressing Ctrl-C also stops observation only. Run watch again to reconnect. To deliberately cancel a running task after approval, use type-cli threads cancel thread_123 --yes. A failed or cancelled watched run exits nonzero.

If watch reports waiting_for_input or waiting_for_approval, inspect the exact pending request:

type-cli approvals list --thread thread_123 --json
type-cli approvals get approval_123 --json
type-cli approvals answer approval_123 --message "Use the October report" --json

For structured questions, use --args '{"answers":[{"question":"exact question","selected":["exact option"],"freeform":null}]}' or --file ./answers.json. Use approvals approve <id> --yes or approvals reject <id> --reason "..." --yes for an ordinary tool approval. Questions require approvals answer; generic approval does not answer them. Specialized app-publish and integration-setup workflows retain their own approval steps.

Creation, reply, and answer receipts include nextActions.argv for the exact continuation. Agents should execute that argument array directly, including any specified stdin, rather than parse the display command. --trigger-message <message-id> keeps watch scoped to the prompt that started the run even if later replies exist; --after-run <run-id> supports manual observation of the next run. A successful submission or approval answer does not prove the task finished. Download returned output file IDs with type-cli files download <file-id> --output ./report.json and inspect the result. After an ambiguous create or reply failure, inspect recent threads before retrying because a new submission may already exist.

Reply in a thread and mention teammates

Post a reply into an existing thread as the signed-in user. This is the counterpart of sessions push: push starts a new thread from a local transcript, reply adds to a thread that already exists.

type-cli threads reply thread_123 --message "@Fletcher Richman can you review this? cc <@user_01…>" --json
type-cli threads reply thread_123 --file ./reply.md --json
type-cli threads reply thread_123 --message - < ./reply.md
type-cli threads reply thread_123 --message "Summarize the decisions above" --reply-mode prompt --json

Mention a teammate by writing @Display Name (case-insensitive, matched against organization members) or <@user_id> (exact; find IDs with type-cli search "<name>" --types users --json). Resolved mentions render as mention chips and notify that person. #space-name links a Space. The thread ID is the root message ID returned by search, threads recent, threads list, or sessions push; a reply’s message ID also works and resolves to its thread.

The result includes the message URL, mentions (who was resolved and notified), and unresolvedMentions (tokens that matched nobody). An entry in unresolvedMentions means nobody was notified for that name, so look the person up and retry with <@user_id> when the mention matters.

A reply is either a Team message (--reply-mode chat), which never starts or resumes an AI response, or an AI prompt (--reply-mode prompt), which asks the thread’s agent to respond. When --reply-mode is omitted, a reply that resolved a user mention is sent as a Team message and any other reply is sent as an AI prompt, so a message addressed to a teammate does not also wake the agent. Replying requires access to the thread’s Space, closed threads reject replies, and direct-message threads are not supported.

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.

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:

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:

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.

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:

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.

Combine an interval with --days to restrict its weekdays, for example --every 1h --days weekdays. The 1m interval is also accepted; the web interface reserves this option for development. A schedule name can be supplied as --name "Morning brief" or as one quoted positional argument, but not both.

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

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 unless you pass --enable on create. Test before enabling:

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. --description <text> adds a description. --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.

Run-setting updates preserve omitted fields. Use --no-fast, --clear-model, or --clear-effort to reset one setting, or --default-model to clear all run overrides. --clear-channel restores the Space’s default destination.

Updates, enable, and disable check the automation’s latest edit version. Pass --expected-version <version> from an earlier get to pin that read; on a conflict, re-read the automation instead of retrying automatically.

Scheduled automations are also editable as artifacts in Type. list and get never convert an older automation; open converts it when needed, keeps its task ID, and prints the artifact URL:

type-cli scheduled-actions open atask_123 --space daily-brief --no-open

Scheduled automation IDs can be inspected and managed without a Space:

type-cli scheduled-actions get atask_123 --json --no-input
type-cli scheduled-actions archive atask_123 --yes --json --no-input
type-cli scheduled-actions delete atask_123 --permanent --yes --json --no-input

These commands resolve the ID within the selected organization, including archived tasks, tasks without a Space binding, and tasks whose agent is no longer the Space’s default. Optional --space constrains the task to that Space and rejects a mismatched binding. automations get <id> --kind scheduled also accepts an omitted Space; --kind event still requires one. Inspect isArchived and editVersion in the response; spaceId is null when unbound. Listing remains Space-scoped and can omit these legacy tasks. Execution and editing commands still require a Space with its current agent.

Archive disables and hides the automation while keeping its configuration and run history. Use disable/enable for a resumable pause; there is no CLI restore command for archives. Legacy delete without --permanent continues to archive:

type-cli scheduled-actions archive atask_123 --space daily-brief --yes
type-cli scheduled-actions delete atask_123 --space daily-brief --permanent --yes

Permanent deletion removes the definition, instructions, memory, and linked artifact revisions. It works with active or archived task IDs and cannot be undone. Run records, delivered messages/files, and shared connections remain. Run records lose their automation link, so history filtered by that automation ID no longer finds them. Already dispatched runs may finish. Historical prompts, transcripts, logs, and backups are outside this deletion’s scope. Archive and permanent deletion accept --expected-version <version> and reject concurrent edits without retrying automatically.

New-thread automations support synced-events archive and synced-events delete --permanent with the same behavior. Other event sources use source-specific synced-events delete: webhooks lose their channel association but retain their source record; RSS feeds lose configuration, tracked entries, and source events; Slack, GitHub, Linear, and email are unsubscribed or disconnected from the Space. Shared integration connections and previously delivered output remain. Inspect automations schema --json for deletion capabilities.

Choose accounts for scheduled actions

Explicit automation account selection is available only to organizations in the rollout. Existing choices remain enforced if the switch is later disabled.

Use --act-as <connection-id>=<account-id> on scheduled-actions create or update to choose which account an automation uses. Discover available connections and account IDs first:

type-cli integrations connections --json
type-cli scheduled-actions update atask_123 --space engineering \
  --act-as orgint_123=intacct_456 --act-as orgint_789=intacct_012

Use the connection’s id and the account ID from organization.integrationAccountId (shared account) or personal.userIntegrationId (your personal account). Personal accounts are allowed only for automations you created.

Repeat --act-as once per connection. Exact connection and account IDs are required; provider names, display names, and team/personal aliases are not accepted. The server checks account ownership and access in every destination Space. scheduled-actions get, list, and mutation results show saved account choices.

Updates preserve choices you do not name. To clear only one connection’s choice:

type-cli scheduled-actions update atask_123 --space engineering --act-as orgint_123=inherit

Clearing a choice does not disconnect the account. When automatic account selection is enabled for your organization, managed automation runs save the account they resolve when they first request an integration’s credentials. A later run can therefore save an account again after you clear its choice. Existing saved choices continue to apply even if automatic selection is disabled.

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:

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" --enable
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.

Slack, GitHub, Linear, and email creation requires --enable: these sources immediately receive events and cannot be created paused. Webhook, RSS, and new-thread sources start disabled unless you pass --enable.

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.

Use get, update, enable, disable, and delete for the rest of the lifecycle. Webhook, RSS, and new-thread sources can be paused with disable. Slack, GitHub, Linear, and email sources cannot be paused; delete them to stop incoming events. Deleting asks for confirmation unless you pass --yes. Use type-cli synced-events --help for source-specific flags.

Email sources cannot be updated. Other sources accept only their supported fields; unsupported options and empty update values are rejected. Use --clear-channel where destination updates are supported. Run type-cli automations schema --json to inspect source capabilities and required flags.

type-cli synced-events update rsssrc_123 --space daily-brief --poll-minutes 60
type-cli synced-events disable whsrc_123 --space daily-brief
type-cli synced-events delete whsrc_123 --space daily-brief --yes

Code-first automations (beta)

Code-first automation authoring and deployment are beta. These commands require the code-first-automations feature switch to be enabled for your organization.

To deploy an automation folder, add a root type.json with its name and source entrypoint:

{
  "name": "Release updates",
  "entrypoint": "src/main.ts"
}

The entrypoint defaults to src/main.ts. Your source defines the automation’s deployment and subscription handlers. An optional root fixtures.json contains an array of host test cases. The CLI validates the fixture envelope locally and sends these cases separately from source files; a nested file such as src/fixtures.json remains a source module. The CLI reads the folder without executing its code locally and respects .gitignore and .typeignore.

type-cli automations deploy ./release-updates --space daily-brief
type-cli automations deployment <deployment-id> --space daily-brief --json
type-cli automations deployment <deployment-id> --space daily-brief --follow

deploy follows validation, fixture execution, subscription registration, and activation. A successful deployment enables the automation; a failed deployment exits with an error. Omitting the folder deploys the current directory.

Keep .type/project.json to preserve the automation’s identity across deployments. .type/deployment.json records the latest attempt, and the CLI prints its deployment ID before submitting it. After an interruption, use deployment --follow with that ID to resume observation. Both commands accept --timeout <seconds> from 1 to 3600, with a default of 600. A timeout ends observation; it does not cancel the server’s deployment.

Expiration can be set in type.json or overridden for one deployment:

type-cli automations deploy ./release-updates --space daily-brief --expires-in 5h
type-cli automations deploy ./release-updates --space daily-brief --max-runs 10
type-cli automations deploy ./release-updates --space daily-brief --expires-at '2026-10-10T10:00:00-06:00'
type-cli automations deploy ./release-updates --space daily-brief --no-expiration

Choose one expiration flag. --expires-in accepts positive whole durations with s, m, h, or d (up to 315576000 seconds). --max-runs accepts a positive whole number. --expires-at requires an ISO timestamp with Z or a UTC offset; the example is 10 am MDT. Past timestamps immediately prevent new runs.

For a persistent project setting, add one of these to type.json: "expiration": { "kind": "duration", "afterSeconds": 18000 }, "expiration": { "kind": "runs", "maxRuns": 10 }, or "expiration": { "kind": "timestamp", "at": "2026-10-10T10:00:00-06:00" }. Use "expiration": null to explicitly remove the source’s expiration.

Precedence is CLI flag, then type.json, then the source’s deployment.expiration. Flags affect the submitted deployment and do not edit local files. A later deploy without flags uses the project/source declaration again. Inspect the saved limit with automations get <automation-id> --space <space> --kind scheduled --json under data.resource.codeExecution.definition.expiration.

Durations start at first activation. Run counts cover all subscriptions, including failed, skipped, repair, and emitted follow-up executions. Replays of the same run and deployment fixtures do not consume another run. Pausing and redeploying retain the original activation time and lifetime count; admitted runs may finish.

For single-file code uploads, scheduled-actions create and update accept the beta flags --code-file <path> or --code <source>, plus --arguments <JSON object> and --agent-invocation code_decides|always|never. Arguments and agent invocation require a code upload. Beta deployment commands and code upload flags are omitted from unauthenticated automations schema discovery.

Inspect and test code automations

These capabilities require code-first-automations for the signed-in user and workspace. Existing report, scratchpad, and retrospective gates still apply. Offline schema discovery stays available without login; use live discovery to include the commands enabled for your session:

type-cli automations schema --live --json
type-cli automations test-code atask_123 --space engineering --arguments-file ./fixture.json --json

test-code runs a fixture against a saved, paused code automation as its creator. It returns the code result and testedDefinitionHash. It does not activate the automation or deliver a real event. Supply a fixture as --arguments '<JSON>' or --arguments-file <path>; --arguments-file - reads stdin. For example:

{"subscriptionId":"hourly","payload":{}}

Fixtures can also supply checkpoints, matcher decisions, and recorded tool or integration responses. See Test with Fixtures. The existing automations tests start and scheduled-actions test commands continue to test agent instructions.

For enabled sessions, scheduled automation inspection includes connection health and human-intervention details. Scratchpad and saved report fields also require their respective feature gates. Run inspection with --run <id> --include-activity --include-content can include code results, call journals, retrospectives, and report errors. These share the redacted --max-chars budget with activity previews. Fields that cannot fit safely are omitted and named in detailContentOmitted; increase the budget up to 48,000 characters to inspect more. Access checks and secondary feature gates still apply.

Change an existing code automation’s expiration without uploading its source again:

type-cli scheduled-actions update atask_123 --space engineering --max-runs 10 --json
type-cli scheduled-actions update atask_123 --space engineering --no-expiration --json

Choose one of --expires-in 7d, --expires-at <ISO timestamp>, --max-runs <count>, or --no-expiration. Patch files and automations plan also accept expiration: a duration, timestamp, or runs object; null removes it. Other update fields keep their existing behavior.

Manage automation reports

These commands require both code-first-automations and automation-visualizations. They edit or export an existing automation report without running the automation.

type-cli automations visualization get atask_123 --space engineering --json
type-cli automations visualization update atask_123 --space engineering --patch-file ./report.json --expected-revision 4 --json
type-cli automations visualization hide atask_123 --space engineering --expected-revision 5 --json
type-cli automations visualization restore atask_123 --space engineering --expected-revision 6 --json
type-cli automations visualization export atask_123 --space engineering --destination json --json

Read the current revision before each edit. A stale --expected-revision fails with version_conflict; read again and review the change before retrying. Hide preserves the saved report, and restore uses that saved specification. The update file contains visualization and optional layoutPrompt, dataSources, and stateSources; use --patch-file - for stdin.

Export accepts json (default) or image. Image export returns the stored file’s metadata. Export does not send email or post to Slack.

Inspect automations with agents

The automations namespace combines discovery, inspection, bounded history, costs, private test observation, and beta folder deployment. Use scheduled-actions and synced-events for lifecycle changes. Use --json --no-input for scripts and agents:

type-cli automations schema --json
type-cli automations schema --kind webhook --json
type-cli automations list --all-spaces --json
type-cli automations list --space daily-brief --kind scheduled --json
type-cli automations get atask_123 --space daily-brief --kind scheduled --json
type-cli automations history --space daily-brief --automation atask_123 --status failed --since 7d --limit 100 --json
type-cli automations costs --space daily-brief --since 30d --json

Schema discovery needs no authentication. It returns command arguments, required flags, enums, source capabilities, and the scheduled-action patch schema. Unsupported flags and extra positional arguments fail instead of being ignored. get requires --kind scheduled|event; list and history also accept all.

Inventory covers accessible Spaces; archived or unbound automations may be absent. History filters run before pagination. Dates accept timezone-qualified ISO timestamps or durations such as 7d; --until is exclusive. Use the returned cursor to continue, and --mode test to select recorded tests. Other provenance can be unknown; --mode live is unavailable. Completion does not prove delivery or business success.

Report automation costs and failures

Use automations to compare recorded automation usage, find expensive runs, and summarize failures. For general workspace spending, use type-cli workspace-analytics costs summary; costs space-detail --space <space-id> provides the same Space breakdown as automations costs without an explicit basis.

type-cli automations costs --org <org> --all-spaces --basis all --period last-month --grain week --compare previous-calendar-period
type-cli automations costs --space <space> --basis raw-tokens --since 7d --group-by run --sort cost-desc --limit 10 --json
type-cli automations history --org <org> --all-spaces --status failed --since 7d --group-by failure-reason
type-cli automations history --space <space> --run <run-id> --include-activity --json

Choose --space or --all-spaces. Costs can group by space, automation, or run; rankings use known subtotals. Pages default to 20 rows (maximum 100). Continue with the returned --cursor; cost summaries cover the matching window, not just the page.

billable-usage reports Type usage against plan allowance, trial credits, or other credits. BYO subscriptions consume no Type usage. raw-tokens values recorded customer tokens at hypothetical API rates, independently of actual subscription or provider charges. Internal/exempt work is excluded. all returns these views separately; do not add them.

Missing records or prices remain unknown. Known subtotals and fully priced recorded runs do not establish complete history; whole-window totals and monetary deltas stay unknown while coverage is incomplete. Invoice amounts, subscription-fee allocation, and model/harness/effort estimates are unavailable. Billable usage does not support run grouping or receipt-specific kind/automation/status/mode filters; choose raw-tokens for those requests.

Costs default to the last 30 days; --until requires --since. Periods such as this-month and last-month use --timezone (default UTC); weeks start Monday. Use --since/--until instead of --period for an explicit window. --compare previous-period compares an equal-duration preceding window; previous-calendar-period requires a calendar period. Requests are limited to 366 days per window and 10,000 records per source across both windows; narrow the window or filters if exceeded.

Organization admins/owners can read cost metadata across Spaces. Thread content, private tests, and activity retain separate permissions. Activity content is omitted unless you pass --include-content; use --max-chars to bound previews. Credential patterns are redacted, but other sensitive content may remain. Run IDs are stable; thread links and stored activity can be unavailable. Use automations costs --help and automations history --help for all filters.

Preview scheduled-action patches

Use a JSON patch file or stdin to edit a scheduled action. Inspect the schema with automations schema --kind scheduled --json; output from automations get is an inspection snapshot, not an apply document.

For example, save this as patch.json:

{
  "description": null,
  "runConfig": { "effort": "low", "fastMode": false }
}

type-cli automations plan atask_123 --space daily-brief --patch-file ./patch.json --json
type-cli scheduled-actions update atask_123 --space daily-brief --patch-file ./patch.json --expected-version <version-from-plan> --json

Omitted top-level fields are preserved. Run-configuration fields merge with the stored configuration; runConfig: null restores agent defaults. A supplied schedule object replaces the schedule. Null clears only fields allowed by the schema. Patch files cannot be combined with authoring flags.

A plan performs no writes. It validates the local patch shape and shows the current version and proposed patch; it does not validate server permissions, destination references, or execution effects. Editing schedules, instructions, destinations, or run settings can clear automation memory. If applying returns version_conflict, re-read before deciding whether the change is still appropriate.

Start and resume private automation tests

type-cli automations tests start atask_123 --space daily-brief --kind scheduled --json
type-cli automations tests get <response-message-id> --space daily-brief --json
type-cli automations tests follow <response-message-id> --space daily-brief --timeout 300 --json

Tests run real agent tools in a private thread, including possible integration writes. They are not sandboxed and do not validate live event routing. Get and follow observe only your private tests; they cannot inspect arbitrary live runs.

Before submission, start prints a receipt to stderr with a response message ID. If the submission result is ambiguous, inspect that ID. To retry the same test, reuse it as --request-id <response-message-id> with the same identity, Space, automation, and kind. To resume observation, use get or follow instead of starting another test. The legacy scheduled-actions test and synced-events test commands also accept --request-id.

Following exits non-zero on execution_failed, execution_cancelled, or observation_timeout. A timeout stops waiting and does not cancel execution; the error retains the ID needed to resume. tests get returns the observed status without treating a failed execution as a failed lookup. Rate limits return rate_limited, distinct from invalid input or version conflicts.

Use integrations

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

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 outside any Space, using the same personal-or-organization credential selection and granular permission policy as Type. Access comes from workspace grants, explicit user grants, integration-manager status, and grants on any unarchived Space the user belongs to. For a shared connection, the highest applicable mode wins. Another member’s personal connection stays limited to the Spaces it is shared with. The list does not include every integration type: Custom API, API-key provider connections, and database connections are not listed.

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

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:

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:

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. To attach a verified connection to a Space, run type-cli spaces connect engineering --integration orgint_123 --yes; inspect it with spaces connections engineering and remove the Space association with spaces disconnect engineering --integration orgint_123 --yes.

Start a personal Gmail connection:

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:

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:

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:

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. The default setup opens a Type form where you enter the credential:

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. For the browser setup, enter it in Type and press Save; use --no-open to receive the setup URL without opening a browser.

For a Custom API, --terminal saves the credential without a Type setup page. Pipe it from a password manager through --secret-stdin and pass --yes after approving the exact connection. The example uses pass; use your password manager’s stdout command. For authScheme: "none", omit --secret-stdin. Do not put the credential in shell history, --config, or a command argument. Verify the returned attempt before using the connection:

pass show warehouse/api-token | type-cli integrations connect custom \
  --scope personal --terminal --secret-stdin --yes \
  --config '{"name":"Warehouse API","baseUrl":"https://api.example.com","authScheme":"bearer","validationRequest":{"path":"/v1/me"}}' \
  --json --no-input

Terminal setup returns an attempt ID and a verifyCommand; run verification before use. Browser setup returns a waitCommand to monitor the exact setup, followed by a verifyCommand:

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; it waits up to 600 seconds by default, or --timeout <seconds>. 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:

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

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

The output lists workspace, user, and personal grants and reports the signed-in user’s CLI-effective mode (effectiveMode). Individual Space grants are omitted from the output, and omittedSpaceGrantCount reports how many were hidden. Grants on unarchived Spaces the user belongs to still count toward effectiveMode, so it can be higher than the grants shown. For a shared organization connection, all applicable grants are additive: the highest applicable mode wins. A user-level read_only grant does not reduce a workspace-level or Space-level full grant. Calls made inside a Space use only that Space’s grant.

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

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:

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:

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:

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.

Change an app’s connection account choice

For an existing Type App, you can prepare a connection-only update without changing its views or actions. Use your own Type account with editor or owner access to the app and access to its Space. You also need a valid personal account for the connection you want to use.

Before pulling, check for pending app updates and coordinate with other maintainers. Use the current CLI and pull the exact existing app into a fresh directory:

type-cli app pull wart_123 --into ./app-connection-update --json --no-input
cd ./app-connection-update

If the checkout requires conversion of an older app, review that conversion separately before continuing.

In .type/integrations.json, find the connection’s existing entries by organizationIntegrationId. To use each viewer’s personal account, set authorizationSource to viewer_personal on those entries. Keep each entry’s alias, operation ID, schema hash, connection slot, and execution settings unchanged, along with all other files and connection choices. This mode supports interactive actions only; resolve any background actions before switching the connection.

The CLI’s app integrations list and add commands discover and add operations; they do not change an existing connection’s account choice. Do not add duplicate entries to make this change. app dev is optional and does not create a hosted draft.

Run type-cli app push --json --no-input, review the returned draft URL and connection access, then publish separately after approval. Saving or pushing does not change an existing app’s live release. If the source changed or another maintainer has pending work, resolve the conflict before continuing; do not force an overwrite.

See Apps: Know whose account the app uses for the account choices, viewer selection, and connection recovery.

Add app integration capabilities

From a linked checkout, discover operations available to the app in its Space. Use an organization integration ID from type-cli integrations list --json; a connection listed there must also be available in the app’s Space.

type-cli app integrations list --connection orgint_123 --kind background_read --query "query postgresql" --json

Each result includes its input schema, allowed execution kinds, operation ID, schema hash, and authorization source. Copy the operation ID from the result and use its schema to construct the fixed input:

type-cli app integrations add --connection orgint_123 --kind background_read --operation native:postgresql:query --alias teamMetrics --input '{"query":"SELECT 1 AS value"}' --max-runs-per-day 24 --json

This appends one capability to .type/integrations.json in the checkout. It copies operationId, schemaHash, and authorizationSource from the server; do not invent those values. If several operations match, select one with --operation. Duplicate aliases and invalid existing manifests are rejected without changing the file.

Background reads require a JSON object in --input and a positive integer daily limit in --max-runs-per-day. For interactive operations, use --kind interactive and omit both options. Discovery does not execute an operation, and adding a capability only changes the local manifest. Review the manifest, then use the normal push and publish flow to validate and approve its capabilities.

Rename or archive an app

Rename a published app or your unpublished draft using its stable ID:

type-cli app rename wart_123 "Inventory overview" --json

Inside a linked checkout, omit the ID: type-cli app rename "Inventory overview" --json. The optional positional target must be an app ID; an existing title is not a rename target. Use type-cli app ls --json to find the ID.

Archive removes a published app for everyone and tears down its hosted backend, or discards your unpublished draft and its development backend. Published-app archive is owner-only and cannot be undone from the CLI. After explicit approval:

type-cli app archive wart_123 --yes --json --no-input

Omit the target to archive the linked app. Archive also accepts a title reference; prefer the stable ID to identify the exact app.

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. Add --draft to open the hosted draft or --data to open the app’s data view.

Read backend logs for the live release, or for the hosted draft with --draft:

type-cli app logs --json
type-cli app logs --draft --tail

Rollback is not available in the CLI. To revert, push the desired source as a new draft and publish it.

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" --space 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" --space 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" --space 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" --space 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.

Discover public library skills

Use type-cli skills discover [query] to browse or search the published Type skills library. No login or organization selection is required. Each call reads the current public catalog.

# Browse the first 20 published skills.
type-cli skills discover

# Search by task, product, or industry.
type-cli skills discover "conversion"
type-cli skills discover "Google Ads"
type-cli skills discover ecommerce --limit 5

# Return structured results for scripts and agents.
type-cli skills discover "revenue" --limit 10 --json --no-input

# Show command help.
type-cli skills discover --help

Search uses a case-insensitive substring match across names, descriptions, slugs, handles, roles, industries, authors, presentation titles and summaries, and file paths. It does not search file contents. A query such as "Google Ads" matches that phrase; use a shorter query if a longer phrase returns no results. Queries with multiple words can be quoted or passed as separate arguments.

Each result shows a title, a summary when available, and a library page URL. Open that URL to inspect or download the skill. Discovery only reads the catalog; it does not install a skill or add it to your workspace.

Limits and JSON results

--limit accepts an integer from 1 to 100 and defaults to 20. Results preserve catalog order. When hasMore is true, increase the limit or narrow the query; discovery has no pagination cursor.

JSON field	Meaning
`ok`	`true` for a successful request, including a search with no matches
`operation`	`skills.discover`
`query`	The trimmed search text, or an empty string when browsing
`libraryUrl`	The public library URL
`skills`	Matching skill metadata, bounded by the limit
`totalMatches`	Number of matches before applying the limit
`returnedItems`	Number of skills included in this response
`appliedLimit`	The requested limit, or the default of 20
`hasMore`	Whether additional matches were omitted by the limit

Each skill includes slug, name, description, handle, roles, businessTypes, authorName, filePaths, and url. When available, presentation includes title, summary, and composition metadata for skillsets and dependencies. Descriptions, handles, and author names can be null. File contents, images, and sample outputs are omitted.

Use presentation.title for the library’s display title, with name as a fallback. For example, with jq installed:

# Print titles from up to 100 published skills.
type-cli skills discover --limit 100 --json \
  | jq -r '.skills[] | (.presentation.title // .name)'

# Print matching titles and links as tab-separated rows.
type-cli skills discover "Google Ads" --json \
  | jq -r '.skills[] | [(.presentation.title // .name), .url] | @tsv'

A successful search with no matches returns skills: [], totalMatches: 0, and hasMore: false, with exit code 0. Invalid limits return invalid_input with exit code 2. Network failures, HTTP errors, and invalid catalog responses return unavailable with exit code 6. With --json, errors use the standard { "ok": false, "error": { "code": "...", "message": "..." } } envelope.

Public library or workspace skills

Task	Command	Authentication
Find published library skills	`type-cli skills discover "conversion"`	None
List workspace-level skills	`type-cli skills list --global`	Required
List skills in a Space	`type-cli skills list --space engineering`	Required
Inspect a workspace skill and its files	`type-cli skills inspect <skill-id-or-handle>`	Required

Public discovery returns library slugs and URLs. These are not workspace skill IDs; follow the returned URL for a public skill. Use skills list to obtain references for skills inspect. The --global and --space targeting flags apply to workspace skill commands, not public discovery. --agent remains a deprecated Space-target alias.

Sync skills to a Space

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

type-cli skills sync ./skills/pr-review --space 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 Space’s agent. On later syncs, Type updates the existing skill.

Preview the change without uploading:

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

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

type-cli skills push ./skills/pr-review --space 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 --space engineering --force

List skills in a Space:

type-cli skills list --space 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 Space.

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

A skill package includes SKILL.md and the contents of the scripts, references, and assets folders; other files in the directory are not uploaded. Packages are limited to 64 files of at most 256 KiB each. 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 --space engineering

type-cli sessions push --from codex --current --space engineering

You can also push a specific transcript file:

type-cli sessions push --file ./handoff/session.jsonl --space 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.

sessions push always starts a new thread. To post into a thread that already exists in Type, including one created by an earlier push, use threads reply with the thread ID from the push result; it can also @mention teammates. Push once to hand the conversation over, then reply as the work progresses.

Add a title:

type-cli sessions push --file ./handoff/session.jsonl --space 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 --space engineering --include-files "notes/*.md"

Preview what will be uploaded:

type-cli sessions push --file ./handoff/session.jsonl --space 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 --space engineering --tail

Report bugs and request features

Agents should submit feedback when they encounter a Type bug or need a missing capability during their work, without waiting for a user request or approval:

type-cli feedback submit --kind bug --title "App preview timed out" \
  --description "While checking the app, the preview failed to load after preparation completed." \
  --json --no-input

type-cli feedback submit --kind feature_request --title "Export automation history" \
  --file ./feature-request.md --json --no-input

Use exactly one of --description or --file; --file - reads piped stdin. Titles accept 1–200 characters and descriptions accept 1–10,000 characters. Describe the attempted task, what broke or what capability is needed, and its impact. Reports go to Type support immediately; there is no confirmation step or --yes flag.

A normal type-cli auth login session is required. Read-only signup credentials cannot submit. Type attaches the authenticated user and selected organization on the server. JSON success includes ok: true, operation: "feedback.submit", kind, and the support threadId. Do not automatically retry a timeout or uncertain submission, because the original report may already exist.

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 --space 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 skill sync responses include a results array. Read each result’s skill.id, skill.url, and target.scope and target.space when present.

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
Skill	`skill_...`, skill handle
Workspace	workspace slug, organization ID
Space	`ch_...`, Space slug, exact name; use `--space` for document, skill, and session targets
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`
Report a Type bug	`type-cli feedback submit --kind bug --title "Short summary" --file ./report.md --json --no-input`
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`
Find threads awaiting a human answer	`type-cli threads recent --waiting-on-input --json`
Read one thread	`type-cli threads get thread_123 --json`
Read candidate threads	`type-cli threads batch thread_123 thread_456 --json`
Start an agent task in a Space	`type-cli threads create --space engineering --message "Summarize the release" --json`
Observe an agent task	`type-cli threads watch thread_123 --json`
Inspect pending input	`type-cli approvals list --thread thread_123 --json`
Upload a task input	`type-cli files upload ./input.csv --space engineering --json`
Reply in a thread and mention a teammate	`type-cli threads reply thread_123 --message "@Jane Doe please review" --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`
Open an automation as an artifact	`type-cli scheduled-actions open atask_123 --space operations`
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`
Discover app integration operations	`type-cli app integrations list --connection orgint_123 --json`
Add an interactive app capability	`type-cli app integrations add --connection orgint_123 --kind interactive --operation <operation-id> --alias lookup`
Rename a Type App	`type-cli app rename wart_123 "New title"`
Archive an approved Type App	`type-cli app archive wart_123 --yes`
Inspect app access	`type-cli app access`
Read app backend logs	`type-cli app logs`
List documents	`type-cli documents list`
Create a document	`type-cli documents push --file ./doc.md --title "Title" --space engineering`
Sync a maintained document	`type-cli documents sync --file ./doc.md --title "Title" --space engineering`
Pull a document	`type-cli documents pull wart_123 --file ./doc.md`
Browse public library skills	`type-cli skills discover`
Search public library skills	`type-cli skills discover "conversion" --json`
List workspace skills	`type-cli skills list --global`
Sync a skill	`type-cli skills sync ./skill --space engineering`
Preview skill sync	`type-cli skills sync ./skill --space engineering --dry-run`
Push a transcript	`type-cli sessions push --file ./session.jsonl --space engineering`
Push current Claude session	`type-cli sessions push --from claude --current --space engineering`
Push current Codex session	`type-cli sessions push --from codex --current --space 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 a Space, list accessible Spaces and use its stable ID:

type-cli spaces list --json
type-cli skills sync ./skill --space ch_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.

Webhook synced-events send accepts --timeout 5..300 (seconds, default 30). A delivery_timeout leaves delivery unconfirmed: inspect the destination Space before retrying, because the original event may already have been received.

Cadence backoff for code automations

For a backoff overview and a link to the scheduling guide, run type-cli automations deploy --help.

Recurring subscriptions accept this stepped schedule:

{
  "kind": "stepped",
  "steps": [
    { "everySeconds": 60, "forSeconds": 3600 },
    { "everySeconds": 600, "forSeconds": 3600 },
    { "everySeconds": 3600, "forSeconds": 21600 },
    { "everySeconds": 86400 }
  ]
}

Set this as subscriptions.<method>.source.schedule in the code-first definition and deploy the folder with type-cli automations deploy ./monitor --space operations --expires-in 4d. For an existing automation, edit its definition and redeploy the same bound project. Chat authoring uses the same recurring subscription contract. This requires code-first-automations; legacy --every schedules retain fixed cadence.

The first run is one interval after activation. Durations and intervals are positive whole minutes; each timed step lasts at least one interval, and intervals cannot decrease. A step includes its endpoint; the next step starts a new interval grid. Only the final step omits forSeconds and continues until automation expiration by duration, run count, or timestamp. Without expiration it continues indefinitely. This changes cadence over elapsed time, independently of execution failures.

Pauses include elapsed time. Resuming skips missed occurrences and keeps the original age; code-only redeploys preserve it too. Changing the schedule starts a new cadence, without resetting the original expiration deadline or run count. scheduled-actions get <id> --space operations --json exposes subscriptionNextDueAt as ISO timestamps per subscription; paused, archived, and expired schedules have no next run. The saved next run also appears on the automation’s trigger in the web view.