---
product: Chilkat
product_version: 11.7.0
language: tcl
language_label: Tcl
document: language guide
---
> Chilkat 11.7.0 · language=tcl · this file: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/guide.md`
> Class pages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/classes/<Class>.md`

# Chilkat for Tcl — language guide — v11.7.0

## 1. Which Chilkat binding this is

This is the **Chilkat Tcl extension**: objects are created with `new CkHttp` and used through commands `CkHttp_MethodName $obj args...`, properties through `CkHttp_put_Port $obj 443` / `CkHttp_get_Port $obj`; string-producing methods also have a lowercase-initial command returning the string. Objects are released with `delete_CkHttp $obj`. This is the only Tcl binding.

## 2. Install and requirements

Download the build for your Tcl version, OS and CPU and `load` it: [https://www.chilkatsoft.com/tcl.asp](https://www.chilkatsoft.com/tcl.asp).

```tcl
load ./chilkat.dll   ;# or chilkat.so / chilkat.dylib
```

## 3. Unlocking and object creation

```tcl
load ./chilkat.dll

# Required once per process, before any other Chilkat object. Any string unlocks a 30-day trial.
set glob [new CkGlobal]
set success [CkGlobal_UnlockBundle $glob "Anything for 30-day trial"]
if {$success != 1} then {
    puts [CkGlobal_lastErrorText $glob]
    exit
}

set http [new CkHttp]
```

- Unlocking only sets a flag in memory: no license files, no network call, so the call is repeated each time the program runs. Extra calls are harmless no-ops; the `Global` object can be discarded afterwards.
- If a program forgets to unlock, Chilkat runs in trial mode and stops working when the trial expires — always include the call, and use the purchased unlock code in production.
- `UnlockBundle` unlocks every class; per-class `UnlockComponent` methods exist only in old code.

## 4. Error model

Chilkat commands **do not raise Tcl errors** for Chilkat-level failures. The note under each method on the class page says how it reports failure: a status command returns `0`; the lowercase-initial string command returns `NULL` (the string) on failure while the uppercase form fills a `CkString` object and returns a status; object-returning commands return a null object; for an int result check `CkHttp_get_LastMethodSuccess $obj`. `CkHttp_lastErrorText $obj` holds the diagnostic in every case.

Literals in Tcl: true is `1`, false is `0`, null/none is `NULL`.

## 5. Strings, bytes and encodings

- Strings are Tcl strings; a `charset` argument names the encoding of the *bytes* being produced or read.
- Binary data goes through `CkByteData` / `CkBinData` objects (`Bd` commands).
- Commands with `2`/`3` suffixes or `Quick*` prefixes are distinct commands, not overloads.

## 6. Object lifetime and threading

Release every object with `delete_CkHttp $obj` (the matching `delete_` command for its class), including objects returned by commands.

A Chilkat object may be used from any thread, but **one object must not be used by two threads at the same time**: create one object per thread or protect it with a lock. Objects are independent — there is no shared global state other than the unlock flag and the few `Global` settings.

## 7. Progress callbacks and async

This binding has **no progress callbacks**. For progress, percent-done or cancellation, use the `*Async` variant of a method (every method with an "Async variant" line on its class page has one). `XAsync` takes the same arguments, returns a `Task` immediately, and the result is read from the task after it finishes: run it, poll `Finished` (or wait), then `GetResultBool` / `GetResultString` / `GetResultBytes` etc.; `PercentDone` and `Cancel` are on the task. No new Async methods are added from 11.7.0 on.

## 8. Common mistakes an AI makes with this binding

1. Using method syntax (`$http QuickGetStr $url`) — the Tcl form is `CkHttp_QuickGetStr $http $url $sb`.
2. Forgetting `delete_CkXxx` on created or returned objects.
3. Omitting `Global.UnlockBundle` (the program runs in trial mode and stops working after 30 days).
4. Inventing members by analogy with other libraries. If a member is not on the class page, it does not exist — look it up rather than guessing.
5. Using deprecated members that older examples still show. The class page lists each one with its replacement; `deprecated.md` lists them all.
6. Ignoring the failure path. Every Chilkat method reports failure (see each method's note); `LastErrorText` says why, and printing it is the first debugging step.
7. Using one Chilkat object from two threads at the same time. Create one object per thread, or protect it with a lock.

## 9. Instructions block for coding agents

Paste into `CLAUDE.md`, `.cursor/rules`, or Copilot instructions:

```
This project uses Chilkat 11.7.0 from Tcl (the Chilkat Tcl extension: new CkHttp, CkHttp_Method $obj ..., delete_CkHttp $obj).
- Reference: https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/ — read guide.md once, then classes/<Class>.md for each class used.
- Call CkGlobal_UnlockBundle [new CkGlobal] ... once at startup; delete_CkXxx every object.
- Commands never raise: check the 0/NULL result and puts [CkXxx_lastErrorText $obj].
- Never use a member that is not on the class page; never use members listed as deprecated.
```

## 10. Classes

[Class index for Tcl](https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/index.md)
